Re: Idea for the Eye Of GNOME documentation

[Shaun McCance <shaunm gnome org>]

On Wed, 2011-05-04 at 20:58 +0200, Mario Blättermann wrote:
> Hi all,
> 
> while translating the new eog manual I'm actually unsatisfied with
> handling the basic functions (provided by eog) and the plugin functions
> (provided by eog-plugins).
> 
> For now, the manual handles all the topics which are related to eog
> *and* eog-plugins, regardless the user has the plugins package at his
> machine or not. In many strings, we find hints that a plugin function is
> only available if eog-plugins is installed.
> 
> My idea: We need a second help stack in the eog-plugins module. All the
> function descriptions related to the plugins should be moved to there,
> and the current topic "Extend functionality" in index.page becomes empty
> when eog-plugins is not installed. We fill up the empty topic with a
> short hint that extended functionality is only available when
> eog-plugins is available. Then we can throw away all the particular
> hints in the manual, and we could better distinguish between basic and
> plugin functions.
> 
> Imagine, a user opens the manual and doesn't read it carefully. »Where
> are all these extra functions, I cannot find anything, fu*** docs!«. Im
> sure we could avoid some trouble this way. I know, Mallard can handle
> such topics from foreign modules. Some time ago, I've tested it with the
> Emerillon manual, where I have outsourced some topics to
> emerillon-plugins. Just for testing purposes, it has never committed to
> the Git anyway.
> 
> Just an idea, but perhaps worth to think about it. If it works as
> expected, we could do it for gedit/gedit-plugins the same way.

I think this is a good idea, and it's exactly what Mallard was
designed to do. I kind of started doing this with the Banshee
community extensions, but I haven't stayed on top of them.

https://gitorious.org/banshee-community-extensions/banshee-community-extensions/trees/master/help

Managing two sets of pages for one document takes a little more
administrative work. Mallard makes it possible, but that doesn't
mean there aren't maintenance tasks involved in e.g. keeping page
IDs and link targets in sync. You have to be careful not to link
inline to pages that might not be there. (Info links are happily
ignored if not valid, but we can't do the same for inline links.)

I think EOG, GEdit, and Banshee are good candidates for doing this
kind of thing. We'll surely hit some kinks, and we can iron them
out. But we won't find them if we never try it in production.

Thanks,
Shaun