scrollkeeper-devel

[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

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

[Gregory L. <gle...@li...>]

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

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

[Eugene O'C. <eug...@su...>]

Dan Mueth wrote:
> 
> 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

So the OMF file will look like this:

   <title shorttitle="Calculator">
     GNOME Calculator Manual V2.0
   </title>

Looks good to me.

The guidelines and definition look good. I wonder whether we should specify a precise number of characters though. Perhaps it would be better to leave some flexibility and say "usually less than 20 characters".  

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

So it's OK to use, for example: 

   <title>
     Calculator
   </title>

until the shorttitle attribute is implemented? The contents of the OMF <title> tag do not have to match the contents of the XML <title> tag? If that's the case, perhaps we can use the original suggestion so that we can easily update the OMF files when the shorttitle attribute is implemented. The original suggestion was:

  <comment>
     GNOME Calculator Manual V2.0
   </comment>
   <title>
     Calculator
   </title>

What do you think?

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

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

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

On Mon, 15 Jul 2002, Eugene O'Connor wrote:

> So it's OK to use, for example: 
> 
>    <title>
>      Calculator
>    </title>
> 
> until the shorttitle attribute is implemented? 

Yes.

> The contents of the OMF <title> tag do not have to match the contents of
> the XML <title> tag? If that's the case, perhaps we can use the original
> suggestion so that we can easily update the OMF files when the 
> shorttitle attribute is implemented. The original suggestion was:
> 
>   <comment>
>      GNOME Calculator Manual V2.0
>    </comment>
>    <title>
>      Calculator
>    </title>
> 
> What do you think?

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 :(

We should use the standard XML comment:

<!--
    <title>
      GNOME Calculator Manual V2.0
    </title>
-->
    <title>
      Calculator
    </title>


-Dan

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

[Eric B. <ba...@kk...>]

I'd like to explain a little bit of the history and my reasoning in
rejecting this idea of either adding a second title or replacing the
title with a shorter version.

The GNOME documentation used to have somewhat short titles before GNOME
2.0.  The titles used to be like "Gedit."  This all changed for GNOME
2.  Why did it change?  I believe that the change came as a result of a
discussion about what types of information should be displayed on the
title page and what information should be displayed on the TOC page. 
There were recommendations for including the author, version,
maintainer, and title at the top of the TOC.  This was rejected by Pat. 
He said, "I'm not saying that the above information is not important, on
the contrary it is vital, but it is meta-information that is aimed at a
different audience than the user."  This vital metadata was put into a
separate title page which came about with contributions from everyone. 
This may not seem very important, but then the titles got bigger from
the examples in both the templates and the sample title page.  Character
Picker Applet Manual V0.2 became the title for the sample title page and
the templates produced MY-GNOME-APPLICATION Manual V2.0.  The titles
were making up for the loss of information in the first page the user
views (TOC page).  This has resulted in large titles which Yelp cannot
handle.  Is the solution to add some more metadata?

On Mon, 2002-07-15 at 12:28, Dan Mueth wrote:
> 
> On Mon, 15 Jul 2002, Eugene O'Connor wrote:
> 
> > So it's OK to use, for example: 
> > 
> >    <title>
> >      Calculator
> >    </title>
> > 
> > until the shorttitle attribute is implemented? 
> 
> Yes.

Yes, this is a very good idea.  The title of a document should be short,
sweet, and to the point.  This problem of cancerous titles which grow
and grow without bounds should be ended.  I would also suggest to make
the title of the Calculator documentation just "Calculator".  The
metadata should describe the type of documentation, the version, the
authors, and the license. Therefore there needs to be two changes made. 
The first change to the OMF file to shorten the title and the second
change to the documentation to alter the title to the shortened title
within the OMF file.

> > The contents of the OMF <title> tag do not have to match the contents of
> > the XML <title> tag? If that's the case, perhaps we can use the original
> > suggestion so that we can easily update the OMF files when the 
> > shorttitle attribute is implemented. The original suggestion was:
> > 
> >   <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.
 
> 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?

With all that I'd like to propose that the GDP shorten the titles in the
documentation which contain redundant information.  The information
taken out of the titles should already be contained in either the
metadata or the title page.  The title changes in the documentation
should propagate to the OMF files and the titles in the <title> tag
should be appropriately changed.

Eric Baudais

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

[Eugene O'C. <eug...@su...>]

I think that the longer titles came about to comply with the GFDL. In the Modifications section, point A, it says:

"Use ... a title distinct ... from those of previous versions (which should, if there were any, be listed in the History section of the Document)."

Using the version number in the title is the simplest way to create a title distinct from previous versions.

The word Manual appears in the title so that people understand that the version number applies to the manual and not to the application or applet.

I think that the word GNOME appears as a hangover from when the word GNOME appeared in either the menu that started the application or applet, or the titlebar of the application window. As such, I agree that it is unnecessary and can be removed from the document title. However, Irene is much closer to this than I am, and I would like to check this with her.

To comply with the GFDL, I think that the document titles must contain the appname, the word Manual, and the version number. 

So, I do still think that we need to add some metadata to the OMF, that is, the shorttitle attribute in the title element.

And so I propose that we implement the shorttitle attribute, and in the meantime proceed with what Dan and I were discussing yesterday, that is:

<!--
    <title>
      GNOME Calculator Manual V2.0
    </title>
-->
    <title>
      Calculator
    </title>

Unlike the <comment> tag I suggested yesterday, this validates against the Scrollkeeper DTD.

Eric Baudais wrote:
> 
> With all that I'd like to propose that the GDP shorten the titles in the
> documentation which contain redundant information.  The information
> taken out of the titles should already be contained in either the
> metadata or the title page.  The title changes in the documentation
> should propagate to the OMF files and the titles in the <title> tag
> should be appropriately changed.
> 
> Eric Baudais
> 
> _______________________________________________
> gnome-doc-list mailing list
> gno...@gn...
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list