Re: Idea for the Eye Of GNOME documentation

[Shaun McCance <shaunm gnome org>]

On Sat, 2011-05-07 at 17:20 -0400, Shaun McCance wrote:
> 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

Let me just add some procedural tips. Your plugin pages are often
going to have guide (and maybe seealso) links to pages from the
core document. They won't be valid when those pages are taken on
their own, but that's OK. They'll work once installed.

But it's useful to run Yelp in the source directory to preview
things. So what I started doing with the Banshee extensions is
creating .page.stub files for pages I know exist in the Banshee
help. If you run Yelp with --editor-mode, the stub files appear.
You don't need to reproduce the content in those files. They're
just there so you have some navigation when previewing. Keep
them in the git directory, but don't add them to Makefile.am.

There's a yelp-check script in yelp-tools that can, among other
things, check all your xref attributes. (I'll make a yelp-tools
release this weekend, finally.) It's going to be less useful for
these pages, because it will report links to the core document
as broken. I can add an option to make it read the stub files
as well.

--
Shaun