[orca-list] I would like your feedback regarding a Yelp 3 question

[Joanmarie Diggs <joanmarie diggs gmail com>]

Hey all.

In a different thread, Attila said this:

2. If I hear right, webkit based Yelp version Orca not spokening short 
> desc field with a section title when jumping section titles with Tab and 
> Shift+Tab keys, gecko based oldest Yelp version Orca spokening section 
> title and section short description (desc field) when jumping section 
> links with Tab and Shift+Tab key combinations.

Right. And this is intentional -- by my design. I can undo it if that's
what everyone wants. But let me explain why I did what I did:

When I mark up a section in Mallard and specify the link text, the
linked text does not include the description; just the link. On the
screen, that link is in blue which makes it visually clear that it is
the link. Yelp then adds in the description based on information in
Mallard, placing that text as regularly-colored text beneath the link. 

If you will recall, when the switch was first made to Mallard, but
people were still using Gecko-based Yelp, several people on the Orca
list started asking questions like:

* Why is there no table of contents any more, you should add a table of 
  contents!

* Why does Orca say "link" after just the link when you arrow, but read
  the short description when you Tab? That's confusing! And it's chatty!

And I think the above questions are valid. The answers were and are:

* The table of contents is still there; it's simply not called a table
  of contents. But you should be able to navigate amongst major topics 
  via structural navigation by heading and Tab as expected amongst
  specific topics.

* When you arrow, you move amongst the actual links and text. Therefore
  Orca says "link" for the link and does not say (or include) the short
  description as part of the link because the short description is not
  part of the link. However, Orca reads the full description when you
  Tab because when you Tab Yelp gives focus to the full section and not
  just the link. So *technically* the correct thing to do is read that
  full section.

But the problem with reading that full section is that it doesn't
resolve those original questions/confusion: A Tabbable table of contents
should just give you the topic, and not the short description. And it
really is confusing that Orca only reads the link when you arrow but
reads both the link and description when you Tab.

So.... One option is to leave things alone and answer users who get
confused. And tell users who don't like the "chatty" table of contents
functionality that they should file a bug against Yelp.

The other option is to tweak what Orca does when you Tab amongst
sections in WebKitGtk when the first item is the link and everything
else in the section is not. And that's what I did. <smile> As a result,
you get the exact same thing when you arrow and when you Tab: Only the
actual link (the thing in blue) is presented. That makes Orca consistent
and it makes the Table of Contents functionality work as expected. If
you want to hear the description, just Down Arrow. If you don't (because
you know it's not the topic you wish to read), just press Tab again.

I personally think that under the circumstances what I have done is the
right thing to do. But I could be totally wrong about that. Therefore,
if all of you want me to have Orca read the full section text when you
Tab, that's easy enough to change. After all, it's what Orca would have
done were it not for my tweak. <smile>

Y'all let me know. Thanks guys!
--joanie