Re: Idea for the Eye Of GNOME documentation

[Mario Blättermann <mariobl freenet de>]

Hi Shaun,

Am 07.05.2011 23:20, schrieb Shaun McCance:
> 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.)

For the time being, we should give it a try for packages which are
hosted on our own git repo, both base and plugins packages. Then keeping
links in sync isn't that hard. In general, we should avoid using *any*
links from the base docs to the plugin docs, and be thrifty with links
vice versa. Perhaps we can avoid such links completely? In the  first
case, any links which refers to plugin functions could link to the
appropriate section in the base docs, which in turn links to the
(sub-index page of the) plugin docs. This way one single reference in
the whole help document could be sufficient.
> 
> 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.
> 
The current master branch could be a playground. Due to eog-plugins is
released in sync with eog, it seems to be simple to keep the docs in
sync, too. Let EOG be the first and only candidate, as Empathy was the
Mallard pioneer in GNOME anyway. Once it works and the obstacles are
removed. Moreover, we have to figure out a convenient way for viewing
the pages from both modules in one help document, for testing purposes.
> Thanks,
> Shaun
> 
Best Regards,
Mario