Re: Idea for the Eye Of GNOME documentation

[Mario Blättermann <mariobl freenet de>]

Am 15.06.2011 08:20, schrieb Tiffany Antopolski:
> Hi Mario,
> 
> 
>     Have a look in the Git. There are two modules which are related to
>     gedit, but don't have a manual: gedit-cossa and gedit-collaboration.
> 
>  
> Okay, I have cloned both of these from git.  I think I will use
> gedit-collaboration to play with.
>  
> 
>     We
>     need to write some documentation therefore (just stubs, only for testing
>     purposes) and setup a gnome-doc-utils/yelp-tools infrastructure. Then
>     the header of the *.page file(s) should look as follows (for
>     gedit-cossa):
> 
>     -----------------------------------------------------------------------
> 
>     <page xmlns="http://projectmallard.org/1.0/";
>          type="topic" style="task"
>          id="gedit-plugins-cossa">
> 
>     <info>
>      <link type="guide" xref="gedit-plugin-guide#gedit-additional-plugins"/>
>      <revision pkgversion="3.0" version="0.1" date="2011-06-14"
>     status="stub"/>
>     ...
>     </info>
> 
>     -----------------------------------------------------------------------
> 
>  
> The docs for these plugins should not have an index.page?  

Yes, indeed. Because it is *not* intended as a stand-alone viewable
documentation, we don't need a start page here.
> 
> How do I setup a gnome-doc-utils/yelp-tools infrastructure?
> 

I've some experience with gnome-doc-utils setups, but I would prefer the
new way with yelp-tools. Well, I could give it a try, although I've
never done this before. Shaun should in any case have a look at it,
before we destroy the module completely ;)

>     Of course, we have to make sure that the plugin manual has landed in the
>     same installation folder as the gedit manual itself.
> 
> 
> How do I make sure this happens?

Good question... Normally, if gedit and its plugins come as distribution
packages (rpm, deb, whatever), the usual prefix for the installation is
/usr. And, of course, the manuals of gedit and its plugins will reside
in /usr/share/gnome/help/gedit. At this way, we have a kind of
"monolithic" manual again. The gedit manual is readable if the plugin's
parts are installed or not, doesn't matter. But imagine some odd cases,
e.g. the gedit manual in /usr and the plugin's manual in /opt, depending
on the packaging policies of a certain distribution. Then the plugin's
part is broken. Well, shouldn't happen that often, but it could
casually... That's why we need a strong cataloging system.

On the other hand, some plugins are installable in the local plugin
folder. Those manuals will never appear in Yelp anyway. But actually, I
cannot imagine a third-party plugin which comes from scratch with a
Mallard documentation, unless we will write one.

Hopefully we get it working as soon as possible, at least for that gedit
plugins as test cases. Stay tuned, I will setup the initial help folder
in gedit-collaboration immediately. After that, our good old guru should
have a look at it please and give some help to integrate it in the
module's autotools stack.

Best Regards,
Mario