[kde-doc-english] Shared Help System

[Richard JOHNSON]

On Tue, Mar 30, 2010 at 09:26:32AM -0500, Shaun McCance wrote:
> Hi folks,
> 
> This is a rough write-up of what Rich and I discussed about
> a shared help system at the Desktop Help Summit about a week
> ago. I'm sending it first to the GNOME and KDE documentation
> lists. I'll send this out to more teams after we've all had
> a chance to comment.

I thought you were sending this to the Xdg list, so I have been watching it
like a hawk :)

> Currently, GNOME installs documents to $DATADIR/gnome/help,
> using the document name and then the language, like so:
> 
>   /usr/share/gnome/help/mydocument/C/
> 
> GNOME references documents using the ghelp: URI scheme, which
> in its most basic form looks like this:
> 
>   ghelp:mydocumnt?somepage
> 
> This scheme has been extended and tortured inside Yelp in mostly
> backwards-compatible but completely undocumented ways over the
> years.
> 
> KDE documents *somewhere*, where that somewhere seems to vary
> from distro to distro. It uses the language first, then the
> document name, like this:
> 
>   /usr/share/doc/kde4/html/C/mydocument

/usr/share/doc/kde/HTML/$$CC/mydocument as well, or where ever the distro's
$DATADIR is located. For KDE, we use $HTML_INSTALL_DIR, which is
$DATADIR/doc/kde{4}/HTML/$$CC/docname.

> It references documents using the help: URI scheme. This is
> effectively a rerooting on a path, and always starts with a
> slash, like this:
> 
>   help:/mydocument
> 
> Because it's a rerooting, you can do arbitrary file lookups
> with it. So something like this works:
> 
>   help:/common/foo/bar.js
> 
> This would point to:
> 
>   usr/share/doc/kde4/html/C/common/foo/bar.js
> 
> (Rich, correct me if I'm wrong please.)

You are correct. We do images like that. "help:/images_location/foo.png"

> KDE and GNOME both also have metadata files. I'm ignoring
> what they do with them, because this proposal doesn't use
> them.

We have the index.docbook.bz2 that is just a tarball of what was built from
index.docbook using meinproc, which is our docbook building tool.

When I have a bit more time free I will go ahead and finish my comments.

-- 
 Name|  Richard JOHNSON
Title|  Developer
  WWW|  http://kde.org
Email|  rjohnson at kde.org
GnuPG|  3578 0981 A21D D662 2A96  7623 F4C1 838C D8C4 4738
 Home|  http://www.nixternal.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 835 bytes
Desc: Digital signature
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20100330/bbff044e/attachment.sig