Re: Shortened titles in OMFs and Yelp

[Gregory Leblanc <gleblanc linuxweasel com>]

I appear to have lost the beginning of this thread, so pay no attention
to the threading.  I believe I've read the whole thread, via the web
archives at mail.gnome.org.

It seems that the discussion is about what titles should be, in terms of
content, and in terms of length.  I figure the best place to start
looking at the needs and uses for a title in documentation is DocBook,
since it's been around longer than OMF, Yelp, and the GDP combined, and
it has a much wider range of users, some of whom would probably have put
in RFEs if the existing title elements were insufficient.  The elements
which seem immediately relavent to this discussion are:
subtitle
title
titleabbrev

Titleabbrev seems to be what folks want, and it's description in TDG
states, "TitleAbbrev holds an abbreviated version of a Title.  One
common use of TitleAbbrev is for the text used in running headers or
footers, when the proper title is too long to be used conviently."

Does anybody see a reason not to simply adopt the element from DocBook
for use in OMF?  Eventually, we'll want DocBook and OMF metadata
elements to have a 1 to 1 mapping, so doing something else seems to be
just asking for more work down the road.


As for GNOME documents using long, ungaingly titles...  Eugene quoted a
bit from the GFDL as the reason that titles have gotten to be quite so
long.  I went and read over a copy of the GFDL, looking for that text. 
It appears in section 4, which is titaled "MODIFICATIONS".  This section
appears to apply to modifications and derivatives of the original work. 
I'd have to say that in most cases, we're not going to need to worry
about having a distinct title from that of the Document when we release
a new version of a manual, even if the original author disappears.  All
the documents from the GDP are written with the intent that they're part
of the GDP, so we should have whatever rights we need to allow people to
use the same title.  I think the GNOME Foundation has copyright
assignment forms now, so if we ask authors to fill out a form, we should
have no worries about keeping the same title between revisions/re-writes
of the manual.  Since we don't need to change the title of the work
every revision, and the version number is pretty clearly redundant
information, I don't think there's any reason to have it in the title.

Eric also stated that "GNOME" and "Manual" we redundant pieces of
information.  GNOME certainly seems to be redundant information, but XML
representation of that really needs some work before it's obvious. 
Here's what's in the gnome-calculator-C.omf file:
    <subject category="GNOME|Applications|Accessories"/>

While that works, I wonder what happened to moving that into a "proper
XML" way of doing things, with sub-elements, instead of having things
crammed into a single attribute separated by special characters?  I'm
sure there's a good argument for why doing things this way isn't good,
but I can't think of what it is.  :)

Looking at the OMF files that I have handy, and the original OMF
specification, it doesn't seem like "manual" is represented elsewhere in
the metadata.  This appears to be confirmed by the documentation on
"Writing Scrollkeeper OMF Files".  Since this information isn't
redundant at this point, I'd have to say that we should keep this
information as part of the title.  The list of valid elements for type
probably needs to be extended, as was discussed some time ago.  The
original list was suitable for the LDP, but isn't broad enough to cover
the expanding scope of OMF.

Please direct replies to the lists, I read both, so I'll take questions
and comments there.  Thanks,
	Greg