Re: Shortened titles in OMFs and Yelp

[Malcolm Tredinnick <malcolm commsecure com au>]

I find this whole thread a little strange, since it seems obvious to me
that allowing a short title in the metadata is a good idea. It can even
be extracted

Eric's post represents an appropriate point to respond to, since he
seems to have laid out the points against the change quite nicely. So
consider this a response in favour of the idea, rather than an attack on
Eric's ideas.

On Mon, Jul 15, 2002 at 01:44:07PM -0500, Eric Baudais wrote:
[...]
> > >   <comment>
> > >      GNOME Calculator Manual V2.0
> > >    </comment>
> > >    <title>
> > >      Calculator
> > >    </title>
> > > 
> > > What do you think?
> 
> I don't like this.  With the title of the documentation being
> "Calculator" the comment tag is redundant.  It describes information
> that is already in the metadata.
> 
> 1) GNOME is in the category.  The category already classifies the
> documentation and you don't need to repeat that classification.
> 
> 2) Calculator is in the title.  It is the title of the documentation and
> should not need to be restated here.
> 
> 3) Manual is in the type.  The type metadata already describes the type
> of documentation.  Again repeated information.
> 
> 4) V2.0 is in the version.  The version metadata describes the version
> of the document along with the date and a short description.  Also
> repeated information.

Consider an alternative wording "Xyzzy Foobar V2.0 manual. In this case,
the document could be at version 2.87 while still only talking about
version 2.0 of the calculator (and you can't drop the 2.0, because that
it was distinguishes it from Foobar 1.0 which contained many less
features). It's still in the GNOME category (just doesn't mention it in
the title) and the application is called Xyzzy Foobar, so you can't
really shorten that (since "Xyzzy" by itself will get confused with
"Xyzzy Baz", another related application). The title is just as long,
but doesn't succumb to any easy forcing into the metadata. The point I
am trying to make here is that if you are going to try and restrict full
titles in such an arbitrary way, then you are implicitly restricting
application names and other things.

> > I like the idea of preserving the original title in the OMF file as a 
> > comment so that the OMF files can be easily updated later.  However, 
> > <comment> is not a valid OMF element.  So, an OMF file which looks like 
> > the above will not validate and the document will not be registered with 
> > ScrollKeeper :(
> 
> Scrollkeeper shouldn't have to break the OMF specification.  The
> metadata should describe the document as fully as possible, but without
> repeating or stating the information in another way.  I believe that the
> OMF specification has done that and should not be changed at all.  Also
> any changes should be questioned thoroughly as to there need.  A couple
> questions should be asked when contemplating a change:
> 
> 1) Does this tag describe new information not already in the other tags?
> 
> 2) Does this tag information which is useful to all the documents?

In both cases a shorter title answers "yes" to these! The new
information is a short title that _cannot_ be algorithmically extracted
in anything but the most simple cases.  The useful information is a
shorter title that can be displayed "when the proper title is too long
to be used conveniently."

The part in quotes in that last paragraph, by the way, is straight from
the DocBook description of the titleabbrev tag. I assume that everybody
who thinks the short title is wrong here is also campaigning to have the
identical DocBook tag removed on the same grounds? After all, that is
for the same purpose (and when I initially saw this thread my thought
was that that was how to extract the right abbreviation for documents).

Malcolm