[Scrollkeeper-devel] Re: Shortened titles in OMFs and Yelp

[Dan M. <mu...@al...>]

This thread has been maturing on gnome-doc-list, but I wanted to add my 
own comments and cross-post it on scrollkeeper-devel...

ScrollKeeper and the variant of the OMF which it is uses is meant to
enable help browsers to provide a nice interface to documentation they
have access to.  While I do not like the idea of moving the ScrollKeeper
varient of the OMF away from the official OMF (and I hope to bring them
into sync at some point), the direction of ScrollKeeper and its metadata
format must be driven by the needs of the end-users and the documentation
browsers they use.

All applications with a user interface have constraints on how much
information they can present at a given time.  For many GUI applications
space is limited and the full proper names of titles may not fit in the
available space (eg. in a display of the contents list showing all the
document categories and titles).  This is a problem with Yelp, but more
generally this will be a problem for many graphical help browsers.  If the
metadata also provides abreviated titles, better help browsers can be made
since titles can be made to more reasonably fit in the available space
(and in many cases will be more readable by the end-user).  (I do not
believe help browsers can intelligently abreviate titles, or that they
should have to.)

I like the idea of introducing an optional attribute to <title>, such as
'shorttitle', for people to include a briefer title.  We should come up
with some guidelines for its use.  As a start: 
* For application manuals, typically just include the application title.  
(ie. omit articles like "The" and words like "Manual")
* A short title should be no longer than ___ characters.  (How many?) 
* Do not include document or application version information

As a definition, we can start with something like: "'shorttitle' is a 
short form (less than ____ characters) of the document title which may 
optionally be used by document browsers where longer, full titles may not 
fit in the available space."

Since existing versions of ScrollKeeper doesn't support the 'shorttitle'
attribute, it seems reasonable for GNOME to use abbreviated titles in the
title element for now (everybody gets to name their own documents, after
all).  

Hopefully we can resolve this issue quickly and add the 'shorttitle'
attribute very soon.  Any opinions on how (or whether) we should implement
the 'shorttitle' attribute and on its use guidelines are welcome and
encouraged.

-Dan