Shared Help System, Take N (for N >= 3)

[Shaun McCance]

On Wed, 2010-05-05 at 15:16 +0200, Stefan.Kost at nokia.com wrote:
> >We do recommend best practices for HTML, DocBook, and Mallard.
> >HTML documents are expected to have an index.html file. Mallard
> >documents are expected to have an index.page file. And DocBook
> >documents are expected to be named index.docbook.
> 
> I think Mallard documents should have a index.mallard file to be consistent.

Unlike DocBook, Mallard actually defines the file name extension.
So this would require changing the Mallard spec to be compliant.
There are rumblings about different types of files for Mallard
documents, such as .cache, .pages, and .info. Most people like
the short extensions for these.

I understand how people could be put off by Mallard taking such
a generic extension like .page, but it's not really designed to
be something you keep in your home directory and double-click
on. So the (admittedly generic) extension is only relevant in
the context of help document lookups.


> >This does not provide a mechanism for installing metadata
> >files. I'm not really interested in doing that anymore, and
> >nobody else seemed to want it either. I can go into reasons
> >why I don't think it matters if anybody wants to hear it.
> 
> So there won't be a structured index of document anymore. Or
> are you taking categories from the desktopfile (assuming that
> there is a beanstalk.desktop)?

For Yelp, the first thing you'll see if you don't give it a URI
is the Desktop Help. I still want to make the full categorized
listing available, but because it isn't the first thing you see,
I don't feel like I need to optimize for it.

My understanding is that KDE actually has a system service that
recognizes newly-installed documents and caches their metadata.

My general take is that document formats can embed metadata, so
there's no need to provide a separate metadata file. We can look
at index.page or index.docbook or index.html and grab the title.
If we need any other metadata (and I suspect there is metadata
that would be useful), we can figure out ways to encode it into
the document files. And we can talk about those things on the
list and add them to this specification.

Thanks,
Shaun