Shared documentation system

[Malcolm Tredinnick]

I have a few thoughts to post later about this shared documentation
stuff, but Shaun's proposal looks generally good to me. However, a few
comments on one of the proposed modifications seem in order...

On Wed, 2003-12-10 at 14:30, Magnus Bergman wrote:
[...] 
> I totally agree that all those goals are very important. I believe this
> proposal take them all in account. There are two major things that needs
> to be included in the standard:
> 
> 1: How applications launch the help reader to display the right help
>    document.

That sounds like unnecessary policy, since it varies between desktops.
Applications using libgnome will have one set of calls to make,
applications using KDE core libraries (whatever they are called. /me has
no clue) would use that infrasturcture, XFCE applications would use
their library support, and so on. These apps would still run
cross-desktop, but they would use the support built into their libraries
to launch the help viewer.

Shaun's proposal thus far has been an example of trying to standardise
policy rather than implementation. Your suggestion feels like it steps
over that line to me.

> 2: How the help viewer can find the document and in what format it
>    should be in.
> 
> For (1) I suggest that applications invoke "helpview <domain>
> [<section>]", where "domain" usually is the name of the applcation and
> "section" is a way to optionally go to a specific part of the
> documentation.
> 
> For (2) there are already fully usable solutions (like man and info),
> but apparently that is not enough. I suggest that we just agree on one
> place in the file system where the files should be placed (for example 
> "<prefix>/doc/HTML/<lang>/<domain>"). And keep just that as the minimum
> requirement. Then have optional extensions for supplying meta data. I
> see no reason why this meta data cannot just be a part of the
> document.

This would make it impossible for anybody to install an application
outside of the system prefix (for example, in their home directory or in
/usr/local) and have the documentation be available.

The usual solution to these types of problems is having an environment
variable that describes the paths to search, plus a default or two. The
"default" would be defined individually by the various help viewer
applications (e.g. if I build Yelp with --prefix=/gnome/head/INSTALL, it
will may use /gnome/head/INSTALL/share/<something> as well as the
contents of $XDG_DOC_FILES). I am bit concerned this may become unwieldy
though (see how big $PATH variables get and why /etc/ld.so.conf exists).

As far as having the metadata as part of the main file goes: one
drawback is the time penalty -- it is faster to read a number of small
files to extract the metadata and see what docs are available (e.g.
.desktop files) than to parse the same number of large document files.

> Then there is the task of designing the help viewer(s), but that can be
> done in just any way, as long as it knows about these two simple things?

Using one application name for the help viewer would mean I could not
have the GNOME help viewer and the KDE help viewer installed and usable
at the same time.

Cheers,
Malcolm