Re: Idea for the Eye Of GNOME documentation

[Shaun McCance <shaunm gnome org>]

On Wed, 2011-06-15 at 20:13 +0200, Mario Blättermann wrote:
> 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.

Right, although for your own sanity, you might want to put some
page.stub files in git, to make it easier to look through the
local pages.

> > 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 ;)

You set it up pretty much exactly like you set it up for the parent
document. Use the same DOC_ID (gnome-doc-utils) or HELP_ID (yelp-tools)
that the parent document uses. Just make sure you don't have any pages
or other files that conflict with files from the parent document.

> 
> >     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.

Actually, plugin pages can go into different prefixes, as long as
they're in the right place in the prefix. The main gedit help files
can be in /usr/share/gnome/help/gedit and the plugin pages can be
in ~/.local/share/gnome/help/gedit. Yelp will pick them all up,
using XDG_DATA_HOME and XDG_DATA_DIRS.

Just let the build tools do the work and don't worry about prefixes.

--
Shaun