Shared documentation system

[Shaun McCance]

On Wed, 2003-12-17 at 03:28, Cornelius Schumacher wrote:
> On Thursday 11 December 2003 20:36, Shaun McCance wrote:
> >
> > Sure, it's more difficult to work with than it ought to be.  And that is
> > something that I'm trying to address.  But distributors that build and
> > ship ScrollKeeper really have no excuse.
> 
> One of the main problems of Scrollkeeper is that it requires merging the 
> documentation meta information after installation of new documentation and 
> unmerging after deinstallation. This is bad for packaging because it requires 
> running extra scripts and creates files which don't correspond to a certain 
> single package. A new documentation meta information standard should address 
> this problem.

Agreed.  The install and uninstall procedures are a pain, and things
always go wrong.

> > > Well, there is the specification at
> > > http://www.freedesktop.org/Standards/desktop-entry-spec. If this isn't
> > > sufficient we should fix that.
> >
> > All right, if that's the only specification on this format, then I stand
> > by my comment.  That's very under-specified.
> 
> What exactly is missing? This standard is widely used, so if it has 
> shortcomings we have to fix them anyway.

Sure, OK.  Certainly any problems I have with that specification aren't
insurmountable.  It's already used for many things, so it's not as if
we'd be introducing some new beast into the desktop.  I'll write up my
criticisms of the specification and send them separately.

> > Having special-case semantics for translations and formattings is sorely
> > insufficient.  You can't anticipate everything people might do to their
> > documents.  In fact, the simple special-casing I've seen doesn't even
> > handle formattings very nicely.  How do I distinguish between a one-page
> > HTML build and a multiple-page HTML build?
> 
> In terms of meta data I would create different meta info files for different 
> formattings. The same for versions, revisisons, translations, whatever. The 
> reason for that is that each "copy" of a document can generally installed 
> independently of the other copies. So each copy has to bring its own 
> metainformation. Otherwise you either would have meta data in the system for 
> documentation which actually isn't present or you would have to merge meta 
> information which comes with a copy into the meta file describing the whole 
> document. That's not desirable as already said above.

Yes, I hadn't thought of that.  Putting everything in a single file does
require merging files for installation, which I think we'd all like to
avoid.  Installing should be as simple as copying a file.

In that case, there needs to be a mechanism for metadata files to say
what they are, so that they can be differentiated from each other.  The
example of mutliple-page versus single-page HTML works well here.  If I
have both things installed on my system, what would be different about
their metadata files so that they can be distinguished?

> > Provide a generalized mechanism to encode variations of a document, and
> > let the metadata speak for itself.  Otherwise you aritifically restrict
> > the utility of the system.
> 
> My suggestion would be to use a similar mechanism as we use it for 
> translations in KHelpcenter: Each variation gets an own meta info file which 
> in some way has a reference to what document it is a variation of. Doing it 
> by adding a suffix to the filename has the advantage that variations of a 
> document can be recognized without opening the file, but this could also be 
> done by some tag inside the file.

I don't like the idea of relying on filename variations to get any sort
of information.  It has the single advantage of being able to recognize
variations without actually opening all the files, but it can get very
unwieldy if you have anything more than just translations of a document
to deal with.  Of course, a recommended naming system would be good, and
a help viewer could optimize any lookups it needs to do based on this,
but I don't want to rely on the naming for information.

We do need some way of stating that multiple documents are variations of
the same thing.  In ScrollKeeper, seriesid is used.  This is basically
just a randomish string you generate once and reuse for all variations
of the document.  It technically works, when used correctly.  The real
problem is that this random string has seemingly no relevance to your
document, so people copy an OMF file from some other project and just
leave the same seriesid in there, because they don't know what it is.

One way would be to have a URL for the document which would be the same
for all variations.  This is the approach I took for the XML format that
I outlined earlier.  So, for instance, if I made a metadata file for the
freedesktop menu specification, the identifying URL would be

http://freedesktop.org/Standards/menu-spec

This doesn't specify any version or language.  It's a top-level URL that
just references the general document.

Perhaps a simpler approach is just to use a string.  For documentation
for an application, the application name could be used.  I'm concerned
that this could lead to naming clashes though.

A variation on this would be to use a simple heirarchy for naming.  This
heirarchy would have nothing to do with the actual presentation of the
documents.  (I still think that should be done using categories and the
menu spec.)  It would just be a simple namespacing mechanism.

All applications would have a name prefixed with "apps/".  Applications
should generally just use apps/<appname> if the have only one piece of
documentation.  The KMail manual would be apps/kmail, and the Evolution
manual would be apps/evolution.  If an application has multiple pieces
of documentation, it can use its application name as an additional
namespace.  So the Glade Turbo Start could be apps/glade/turbo-start,
and the Glade FAQ could be apps/glade/faq.

GNOME could use the gnome/ namespace for any desktop documentation such
as the User Guide, Accessibility Guide, or System Administrator Guide. 
KDE could, of course, do likewise.  A system/ namespace would probably
be good.

This is essentially the same thing that man does.  It doesn't guarantee
you'll have no naming clashes, but it reduces the risk somewhat.  And at
least for applications, if there is a clash, you've got a more serious
problem than your documentation not working.

--
Shaun