Re: Idea for the Eye Of GNOME documentation

[Mario Blättermann <mariobl freenet de>]

Hi Shaun,

I've just committed the help folder to gedit-collaboration. For the time
being, only the folder, the autotools stuff not yet. Would you be so
kind to review it please?

Am 15.06.2011 20:52, schrieb Shaun McCance:
> 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.
> 
OK, I've done it at this way. I've taken the skeleton from the master
branch in gnome-user-docs, which seems to be the only known example for
a yelp-tools setup.

>>
>>>     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.
> 
Nice to know! I didn't ever thought that it is so simple.

Currently the gedit manual builds with gnome-doc-utils, but if we use
yelp-tools for gedit-collaboration, would it work as expected? Or should
we migrate the sole manual (gedit itself) to yelp-tools before?

In my mind, we don't need to declare a license within the text of the
plugin docs, but we should add a license hint to the module. In any
case, the embedded plugin *.page files will inherit the license from
gedit's manual.

Cheers,
Mario