Shared documentation system

[Shaun McCance]

On Thu, 2003-12-11 at 10:15, Cornelius Schumacher wrote:
> On Monday 08 December 2003 08:44, Shaun McCance wrote:
> > On Sun, 2003-12-07 at 22:51, Cornelius Schumacher wrote:
> > > On Monday 08 December 2003 01:10, Shaun McCance wrote:
> >
> > [snip]
> >
> > > > In the case of mixing applications from different desktops, the
> > > > proble misn't devastating.  Most users will get the help for an
> > > > application by selecting it from the Help menu.  In KMail, that will
> > > > open up the KDE Help Center.  In Evolution, that will open up Yelp.
> > > >
> > > > This presents a problem for third-party software, though.  When ISVs
> > > > develop documentation for their applications, what do they do?  If
> > > > they have to jump through hoops to make it work with different
> > > > desktops, then they probably just won't bother.  They'll put it in
> > > > HTML and open a webbrowser.
> > >
> > > Yes, you are completely right. The desktop file approach of KHelpCenter
> > > already makes it quite easy to add 3rd party documentation. SUSE for
> > > example uses this mechanism to integrate the documentation of the
> > > complete distribution into the help center. It also provides an
> > > apache-based help browser for these docs using the same meta files as
> > > the KHelpCenter.
> >
> > Oh certainly.  It's not that nobody can use these systems.  It's not all
> > that difficult to stick something in ScrollKeeper either.  But for one
> > reason or another, people don't use them as much as they could.  Right
> > now I'm using Fedora Core 1.  Fedora has a ton of documentation, but
> > none if it is in ScrollKeeper.
> 
> Using Scrollkeeper is quite complex for developers, especially for packaging. 
> I suppose if the same effect can be achieved with a simple hand-written file 
> which doesn't add any new dependencies to the package adding meta information 
> for documentation would have a chance of wider acceptance.

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.

[snip]

> > I think it's very beneficial to have all documentation work the same
> > way, and to have stuff like the applications categorization and the
> > documentation categorization work as similarly as possible.
> 
> Yes, but at least for backwards compatibility it would be nice, if the more 
> complex application categorization mechanism wouldn't be mandatory for the 
> docs from the beginning on. This would also make life for help browser 
> developers easier.

I'm entirely in favor of building compatibility with existing systems
into the help system.  The correct way of doing this is to specify the
semantics of the help system, and then to specify how conditions of the
other help systems are to map to this system's semantics.

[snip]

> > As for using .desktop files for the metadata, I have a few reservations,
> > but I'm not entirely opposed.  One problem I have is that the syntax
> > isn't, to my knowledge, well-defined.  At least I don't know of a real
> > specification on them.
> 
> 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.

> > With XML, I have a clearly-defined syntax, and I have a fully conformant
> > parser available to me.  In fact, one of the main reasons I concocted my
> > own XML format, rather than using actual RDF/XML, is that if I were to
> > use RDF/XML, I would feel compelled to support it fully, not some half
> > ass subset.  And I don't have an RDF library readily available.
> 
> We have parsers for the desktop files as well. In KDE there is a class 
> KDesktopFile. I assume there is someting similar in GNOME, isn't it?

Yes, but since I don't have a clear specification on what the format is,
I have no way of determining whether GNOME's library is conformant.  The
only criterion I have for what's correct is what is handled by the GNOME
implementation.  A reference implementation, however useful, should not
be considered a substitute for a clear specification.

[snip]

> > Another problem I have with .desktop files is that it's not clear to me
> > how to do any nesting.  What I outlined allowed a single metadata file
> > to reference many different "copies" of the same document.  This sort of
> > information can be immensely useful.  It may not be immediately relevant
> > to a simple help viewer, but the worst mistake you can make when making
> > this sort of thing is that the only thing using your system will be the
> > help viewer.
> 
> For what cases would you need the concept of copies? For translations of 
> documents this is handled by KHelpCenter by having the same desktop file with 
> multiple extensions.

Versions, drafts, copy edits, revisions, editorial annotations,
translations, formattings, etc.

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?

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.

> > So I have other motives here.  Every now and then, when I get a bit
> > tired of putting bugs into Yelp, I take a little time off hacking to
> > make empty promises to people.  And one of the things I promise is an
> > automatic documentation for the web building tool.  And I mean fully
> > automatic.  The *model* presented by the format works very well this.
> 
> I don't quite follow you here. What documentation for which web building tool 
> do you mean?

Well, in particular, all GNOME documentation for the web.  But it isn't
the particulars that matter here.  One of my stated goals is that the
help system not assume that only desktop help viewers are using it.

> > > If there is interest I could post a more detailed description of the
> > > meta information KHelpCenter uses right now. It's similar to what you
> > > suggested to put into the XML files.
> >
> > That would be good.  Since you're actually using these sorts of files
> > already, you'd have a better idea of what can be done with them.  The
> > .desktop files are easier to hand-edit, and developers will be more
> > familiar with them, so there is definately an advantage to using them.
> > If I can be convinced that they won't cripple the ability to store
> > meaningful information, I won't really have any objections.
> 
> I have attached the current documentation of the meta data KHelpCenter 
> currently uses.

Thanks for this.  I'm still looking it over.

--
Shaun