Shared documentation system

[Shaun McCance]

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.

So if there's a common system, it's just that much easier for people to
get their documentation to show up.  And hopefully it would also mean we
have more people behind the system, and thus more people to smack others
when they don't register their documents with the help system.

[snip]

> > What I'm proposing
> > ------------------
> > I would like to see something very similar to the way applications
> > are registered.  Every piece of documentation would place a metadata
> > file in a predetermined location.  Then the help browser would use
> > something like the Menu spec to construct a listing of installed
> > documentation.
> >
> > In fact, the applications Menu and the documentation Menu could
> > probably even be merged.  Code that's constructing a menu of
> > applications would ignore elements relating to documentation, and
> > vice versa.  Doing this has the advantage that changing the
> > organization of the applications automatically changes the
> > organization of the documentation to match.
> >
> > As far as I know, this is similar to how KDE deals with documentation
> > right now.  I want to make it more sophisticated.  Instead of using
> > the DocPath field in .desktop files, I want to use a specialized file
> > format that's capable of actually describing the document.  RDF/XML
> > seems like a natural fit for this, except that it's a royal PITA.
> 
> You are right. That's similar to how KDE does it right now. It uses 
> desktop files as meta information. For 3rd party apps it currently 
> doesn't use the mechanism for creating the hierarchy as described in 
> the Desktop Menu Specification but simply uses the directory structure 
> of the meta files as hierarchy (including some .directory desktop files 
> for describing the directories itself). It might be desirable to merge 
> this in the future, so that the same mechanism is used for the menu and 
> the docs for all documents.

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.

Surprisingly few people in GNOME know how to work with ScrollKeeper. 
They just put some weird files in their build tools that they don't
understand and hope for the best.

And even I find myself sometimes wondering something like "Where the
hell is the documentation for Foo located in the categorization?"  If
the structure mimicked the applications menu, then documents would be
easier to find.  Obviously, the categorization has to have more than
just the applications, because there is documentation that doesn't
belong to any application.

> I think your proposal makes perfect sense, but I would like to suggest
> a modification of the file format. Although RDF/XML certainly is a
> viable solution I think using desktop files has some advantages:
> 
> - It's consistent with the meta files used for creating the menu and 
> could possibly even use the same files.
> - Desktop files are simpler and faster to parse
> - Desktop files are simpler to create
> 
> So my suggestion would be to come to a common desktop file definition 
> based on the one currently used by KHelpCenter and use this as meta 
> information for the desktop help systems. The current definition is 
> quite generic and contains fields for (translated) summaries and 
> descriptions, information how to search the doc and some special 
> information (e.g for integrating man and info pages). Hierarchy is 
> reflected by hierarchy of the meta files.

All right, I don't really like having the categorization strictly follow
the heirarchy of files in the filesystem.  I think the Menu spec took a
huge step forward on that, and we should follow.

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.

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.

This problem clearly isn't insurmountable, as we do use the .desktop
format all over the place already.  I've just had my share of experience
with documentation systems which weren't clearly defined in some manner,
and people took advantage of things that "happened to work".  This can
become a real pain in the ass.

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.

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.

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

--
Shaun