Shared documentation system

[Magnus Bergman]

On Wed, 10 Dec 2003 15:02:51 +1100
Malcolm Tredinnick <malcolm at commsecure.com.au> wrote:

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

Well, I see what you describe as a problem this suggestion was meant to
solve. The desktop only needs one help viewer, the applications doesn't
have to care about which it is. I want to chose my favourite help viewer
and have every application use that one.

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

It is possible that it isn't desired, but it was mentioned as goal in
Shauns post (at least according to my interpretation). If each
environment is required to have their own help viewer in order to work,
then they could as well have their own policies for everything as well?

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

I am well aware of this problem since I install every package in it's
own prefix, but (as you point out) it's a common problem. Perhaps the
standard should say that they help viewer must also look in /usr and
/usr/local apart from it's own prefix? Do we also need a standard name
of the environment variablr to use?

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

I didn't really mean that the meta data must be embedded in large
document files, it could be a smaller file living besides the larger
files. My point was that the meta data should not be stored somewhere
else, rather be considered a part of the documentation. And how to store
if should be considered a part of the specification on which file
formats to use, rather than a separate issue, IMHO.

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

If you really want to do that you can have different commands to invoke
them, in the same way as you can have different versions of the same
viewer. But my assumption is that must people don't want that (they even
want to avoid it), they want to use their favourite viewer all the time.