Re: Controlling 3rd-party content in Mallard

[Shaun McCance <shaunm gnome org>]

On Sat, 2010-01-23 at 15:23 +0000, Phil Bull wrote:
> Hi guys,
> 
> We've been discussing Mallard quite heavily on the Ubuntu Docs list over
> the past week. One issue that came up (via Kyle Nitzsche, see his
> original message here [1]) is that people could install their own pages
> in the same directory as the official Ubuntu documentation.
> 
> In some situations this would be useful, for example when a different
> default browser is chosen. The potential for misuse is massive, though;
> third-party developers could pretty much take over the official docs if
> they wanted to, putting links to their content in irrelevant places.
> This would be a nightmare for users.
> 
> Is there any way of restricting what can link in to certain documents?
> One thought I had was that restrictions could optionally be made by
> publisher, and each publisher could digitally-sign their documents. This
> seems a bit complicated, though.

So let's identify three ways that the system docs could be
modified by third-party packages:

1) The package installs files over the system files.
2) The package installs files with the same name somewhere higher
in $XDG_DATA_DIRS.  Notably, /usr/local/share.
3) The package installs pages that link into system pages.

(3) is the only thing that's new in Mallard, and it's the least
disastrous.  At least with (3), all packages can do is add cruft
into your docs.  They can't remove anything.  (I don't mean to
downplay the danger of this, though.  I'll be the first person
to tell you that extra cruft can ruin the usability of perfectly
good content.)

(1) probably can't happen with packages installed through the
packaging system, because packaging systems are very finicky
about every file belonging to one and only one package.  But
a source tarball or a binary installer could do it.

(2) is something people might not know about.  Help files are
looked up by $XDG_DATA_DIRS.  This is true for DocBook as well.
I could override user-guide.xml completely by just installing
a file with the same name in /usr/local/share.

I'm not really sure there's anything we can do about (1) and
(2).  I also think they're only likely to be done maliciously.
And frankly, if a malicious package is being installed, root
privileges and all, documentation is the least of your worries. 

But with (3), which is what Mallard introduces, I could see
packages doing this not because the developers are ass hats,
but just because they're over-eager and think their material
is really that important.

So, can we introduce a system where pages have to be signed
and verified to be included?  Sure.  It's not something I'd
want to put into the core Mallard spec.  But it could be an
extension, and we could support that extension in Yelp.  We
need to be careful to do it in a way that doesn't require
Yelp to have any secret keys.  That's just untenable, not
to mention non-free.  And there's also performance issues
to deal with.

I'm not saying no to this.  But I'm out of town for the rest
of the weekend, and can't really look more deeply into what
it would take.  (And I've got a few dozen other things on my
plate for next week.)  If anybody would like to look into
digital signatures and come up with a rough proposal, that
would help drive this.  We definitely need to get to the
point where other people can draft and propose extensions
to Mallard.

--
Shaun