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

[Simos Xenitellis <simos gnome org>]

O/H Shaun McCance έγραψε:
> On Wed, 2006-02-08 at 11:42 +0200, Alexander Shopov wrote:
>>> I am neither a Debian developer nor a Debian user.
>> Neither am I.
>>
>>> Although
>>> I often try out various distributions, just to see how Gnome
>>> looks across the board,
>> As I am the committer of the Bulgarian Gnome translation team, I' ve had
>> to hunt down one or two bugs/quirks in Debian to improve the experience
>> of Bulgarian users.
>>
>>> I've been considering a change of license since before Debian
>>> first raised their FDL concerns, and I've been strongly in
>>> favor of a change since before Debian's recent ultimatum.
>> My practical issues for a license change is that the Bulgarian
>> translation team has translated the 2.6 Gnome Manual and updated some
>> sections to the new versions. The translations have not been committed
>> to Gnome CVS due to both my lack of time and my inability to understand
>> how exactly to convert our version which was generated via a Wiki to a
>> version that could be committed back to the CVS.
>>
>> I am not in favor of having to retranslate something of the same size or
>> have to think of ways to relicense translations.
>>
>> I am fine with not having this translation appear in Windows Vista and I
>> am similarly fine with having it in the non-free section of Debian.
>
> Danilo and I both put a lot of work into making our documentation
> translatable with PO files, because that's what the translation
> teams wanted.  If that's not an adequate solution, then people
> need to tell me.
>
> Converting to DocBook from a Wiki is nearly impossible.  We can
> make vaguely passable DocBook, with paragraphs and such.  But
> DocBook is far more verbose and expressive than any Wiki syntax
> I've seen.  There's just no way to get all the elements right.
> I can't be responsible for every set of tools that every last
> person has used for creating documentation.
There is a wiki, DocBookWiki, that saves the text files as DocBook XML
and supports the most common tags,
http://doc-book.sourceforge.net/homepage/
At this page you can test with the Albanian constitution (first demo
site). The u/p is editor/editor.
Currently it appears that DocBookWiki is a one-man job; nevertheless
Dashamir does a good work with regular releases.
>
> I am not going to screw over every writer and every translator
> by insisting that the entirety of our documentation stack be
> rewritten from scratch.  Right now, we are considering changing
> licenses.  There are many factors to be weighed, including the
> amount of writer and translator effort involved.  Let's not get
> worked up about a problem that doesn't exist.  We will do this
> right.
>
>>> Debian's primary objections are the quirky language around
>>> the DRM and transparent copy stuff, as well as the usage of
>>> invariant sections.
>> Debian is not a single entity - it is comprised of its developers and
>> not everyone agrees that there are in fact such issues. Thus - I would
>> not accept your statement as valid.
>> More formally - what you are saying has not been voted by Debian and is
>> not their official position yet. Let us not give strength to one of
>> their internal groups by identifying the objections of some individuals
>> with the whole society of Debian.
>
> Fine, but it was you who referred to "the Debian hypocrites".
> There are *individuals* in Debian who oppose the GFDL because
> they believe it's non-free.  And there are *individuals* in
> Debian who support and maintain the non-free repositories.
> Are they the same people?  If not, I fail to see any how you
> can accuse anybody of hypocrisy.
>
>> As we both are not Debian developers - it is not up to us and this is
>> not the mail list for such discussions. My concern is that the internal
>> Debian turmoils do not overflow over to Gnome documentation.
>>
>>> My issues with the FDL are more with its requirements with
>>> respect to revision history and such.
>> I am not a specialist in these issues. I will try to get more
>> information on this.
>>
>>> Furthermore, with the long-term goal of having pluggable
>>> help files, it won't even be immediately clear where one
>>> document ends and another begins.  Using the FDL, we'll
>>> have to start maintaining revision history on a per-topic
>>> basis, and Yelp will have to provide all sorts of mumbo
>>> jumbo to allow documents to be compliant.
>> Are not all manuals versioned in CVS? Are there no commit logs? But I
>> might be mistaken, I will read more on this.
>
> It's not sufficient.  The FDL demands that this information
> be visible on the title page of the document.  CVS version
> information isn't even in the source tarballs, let alone
> binary packages or installations.
>
> Furthermore, for non-printed works, "title page" has a very
> peculiar definition in the FDL:
>
>     For works in formats which do not have any title page as
>     such, "Title Page" means the text near the most prominent
>     appearance of the work's title, preceding the beginning of
>     the body of the text.
>
> People have complained elsewhere that Norm's stylesheets put
> all this crap right at the top of the index page (by default,
> at least), making you sift through it all before you can read
> a document.  And I've pointed out that my stylesheets put it
> all on a separate page, prominently linked.  From this passage,
> it's pretty clear that Yelp is preventing documents from being
> fully compliant with the FDL.
>
> 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/

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

Simos