Gnome documentation used in Ubuntu distributions

[Matthew East]

Hi,

I'm taking this back on the mailing list because it raises some
important issues.

* Jim Kissel:
> Matthew,
> 
> Thank you for reply to:
> "what is the location of XML files displayed by Yelp?"
> https://answers.launchpad.net/ubuntu-doc/+question/8197
> 
> Please take the time to read and understand the problem I am having.  I
> want to contribute to Ubnutu documentation, but I can't get started.

I did read and understand the problem... but your email now allows me to
give you a better answer. In fact, you've come across something that we
have never tried to do before. So, thanks for persevering with this.

>> Matthew East proposed the following answer:
>> I think you've had an answer to this on the mailing list from Phil and
>> myself, but to clarify - that file *is* the Gnome documentation. The
>> source is stored by the Gnome documentation team in their svn
>> repository.
> 
> I've had "an answer", but it doesn't resolve my problem of how to update
> Gnome based documentation that is part of a Ubuntu distribution.  There
> are minor but significant differences between the two documentation  sets.

So, my answer says that the file used in Ubuntu *is* the Gnome
documentation. That's correct, the documentation you are referring to is
part of Gnome, not part of Ubuntu. What we do is simply link to the file
in the Gnome documentation from the Ubuntu documentation, so that when
you click on that link, and read the "desktop sessions" section, what
you are doing is reading the Gnome documentation. We don't amend it, we
don't copy it, we simply link to it and that makes it look like it is
part of the Ubuntu documentation.

The file itself is not shipped in the ubuntu-docs package at all, it
comes from the gnome-user-guide package.

> Specifically in Yelp (Feisty) if you navigate to:
> New_to_Ubuntu -> Basic computer skill -> Desktop Sessions -> Locking
> Your Screen
> which corresponds to:
> https://help.ubuntu.com/7.04/user-guide/C/lock-screen.html
> you will find that it is different from the gnome version found at:
> http://www.gnome.org/learn/users-guide/latest/lock-screen.html

Now that you've posted the last link, I understand where your confusion
comes from.

The Gnome document you have pointed to is for version 2.14 of Gnome, as
you can see from the index page -
http://www.gnome.org/learn/users-guide/latest/index.html

They haven't updated the website for a year or so. So the version of the
Gnome documentation which you see in Ubuntu is in fact the latest one.
*But*, as you rightly mention, it's wrong, see below.

> and the Ubuntu version is incorrect, in my opinion, as there is no "Lock
> Screen" option under the System menu.  At least there isn't on the two
> copies of Feisty that I have running.

Hopefully it will be clear if you have read/understood this far that
there isn't a difference between the Ubuntu version and the Gnome
version of the document - the Gnome website is simply out of date.

But, you're quite right to point out that the document is wrong. The
reason that the document is wrong is that Ubuntu makes some special
customisations to its Gnome desktop, one of which is to remove the lock
screen button from the menu.

Now we get to the tricky bit, the solution. There is currently no
process by which we modify the Gnome documentation to compensate for
Ubuntu-specific changes to the desktop. I have two alternatives.

=1=

We could modify the package which the relevant file is in:
gnome-user-guide. This is not something that the docteam has ever tried
before. You can get started by doing "apt-get source gnome-user-guide"
(which gets you the gnome-user-docs source package) and then you'll need
to create an Ubuntu-specific patch which is applied to the text.

I don't know how difficult this will be, because I've never investigated
whether it is possible to maintain patches on text in packages. We
should ask one of the Ubuntu developers, or specifically the Ubuntu
Gnome maintainers, for some guidance, I think.

=2=

Instead of directly linking to the Gnome documents as we currently do,
we could copy them, import them into *our* repository/package, and make
amendments there. This would require a fair amount of care about keeping
them up to date, and importing translations, but might be possible.

I'd be interested to hear what people think about the best way to
approach this.

Matt
-- 
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20070614/7fcef051/attachment.pgp>