After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 577481 - Feature Request - Skim Reading
Feature Request - Skim Reading
Status: RESOLVED OBSOLETE
Product: orca
Classification: Applications
Component: general
2.26.x
Other All
: Normal enhancement
: ---
Assigned To: Orca Maintainers
Orca Maintainers
3.0! review
Depends on:
Blocks: Andalucia
 
 
Reported: 2009-03-31 15:34 UTC by james.austin1984
Modified: 2015-11-12 06:59 UTC
See Also:
GNOME target: ---
GNOME version: Unversioned Enhancement


Attachments
Adds basic skim read feature, reads first line/ sentence of each paragraph. (6.73 KB, patch)
2010-07-14 08:48 UTC, Dattatray Bhat
none Details | Review
Patch adding skim reading, navigation by sentence & paragraph (18.33 KB, patch)
2010-08-10 06:40 UTC, Dattatray Bhat
needs-work Details | Review
Orca: Adds the basic skim reading feature. (14.78 KB, patch)
2010-11-16 09:34 UTC, Dattatray Bhat
none Details | Review
Orca: Add Skim Reading to OOo Writer, Firefox, Gedit, Evolution (16.53 KB, patch)
2010-11-26 16:46 UTC, Dattatray Bhat
none Details | Review
Orca SkimRead (8.01 KB, application/x-compressed-tar)
2014-09-18 12:07 UTC, dhairyashil
  Details
Orca-SkimRead-patch (20.48 KB, patch)
2014-09-22 09:23 UTC, dhairyashil
none Details | Review
ReadMe for SkimRead feature (4.67 KB, application/octet-stream)
2014-09-22 09:27 UTC, dhairyashil
  Details

Description james.austin1984 2009-03-31 15:34:06 UTC
Would it be ppossible to have a Skim reading feature please? I have found this to be a very invaluable feature in JAWS. Basically JFW skims through long documents and can create links to the first sentence of the paragraph (default) You can then skip straight to that point. You can also define your own criteria for skim reading. 

There may be a problem with this however in that I think JFW uses a virtual /buffer viewer to allow the user to navigate and select these links. I do not know how the Orca team would get around any problems but I still think it would be a very good feature especially if we hope to show that Linux is a viable system for the blind. Not only an every-day but also studying and working environments.
Comment 1 Joanmarie Diggs (IRC: joanie) 2009-03-31 16:29:17 UTC
Hi James.

Thanks so much for filing this enhancement request! It sounds like an interesting idea. The exact implementation would be something that needs consideration of course, but the short response to your concern is that these items could be made selectable via a Gtk+ list/tree in a simple dialog which, potentially, could be created on the fly.

As a general rule don't think in terms of how some other screen reader does it; instead think of what you need Orca to do functionally, like allow you to skim documents. :-) Then we can worry about widgets. :-)

Thanks again!
Comment 3 Dattatray Bhat 2010-06-01 11:03:39 UTC
Skim reading seems to be a useful feature to have in Orca. May I start work on this request please? I have just contributed a bit to another enhancement request 616820. Regards.
Comment 4 Joanmarie Diggs (IRC: joanie) 2010-06-01 12:19:53 UTC
Hi Dattatray.

This is one of the bugs identified as a potential task for those doing the work for Consorcio Fernando de los Ríos. However, I just checked with Alejandro, and he's ok with it. Therefore, feel free to give it a shot.

Thanks!
Comment 5 Dattatray Bhat 2010-06-14 05:09:06 UTC
Hi Joanmarie

Really sorry for the delay in acknowledging your quick reply! Though I am new to Orca and Python, I will make an attempt to add this feature. As the first step, I am studying how the existing flat_review features work.  

The file flat_review.py calls functions queryText(), getTextAtOffset() etc. I cannot locate the implementation of these functions. Where are they defined? Through what mechanism can flat_review.py access them? These questions may be quite elementary, but they have confused me. Can you provide some hints please?

Regards.

Dattatray Bhat
Comment 6 Dattatray Bhat 2010-06-14 17:02:20 UTC
Hi Joanmarie

I had posted the above query in orca-list. Jason and Jon have answered it.

Regards.

Dattatray Bhat
Comment 7 Joanmarie Diggs (IRC: joanie) 2010-07-05 01:58:33 UTC
Planning spam. Sorry!
Comment 8 Dattatray Bhat 2010-07-14 08:48:05 UTC
Created attachment 165853 [details] [review]
Adds basic skim read feature, reads first line/ sentence of each paragraph.

This patch adds the basic Skim Read function to Orca. When user issues the 'Skim Read' command (Ctrl + KP_Add in desktop, Orca + Ctrl + semicolon in laptop), Orca skims through the entire document reading only the beginning portion of each paragraph. The beginning portion is either the first line or the first sentence, depending on the Say All By setting.

Skim reading calls the same functions as those called during say all viz. sayAll() and textLines() in default.py. An additional default parameter (SKIMREAD = False) is added to both the functions, altering the behaviour of a loop in textLines() which collects lines/ sentences from a text object. When SKIMREAD is True,the loop is broken after first iteration because only the first line/ sentence of each paragraph is to be spoken.

There is another minor change in textlines(). Consider the case when Say All By is set to sentence. If a text object does not support reading by sentence, the reading mode is changed and the text is read by line. This results in all subsequent text objects being read by line even if they support reading by sentence. The problem is solved by resetting the reading mode to Say All By before reading each text object.

Please test the patch and give your feedback.

Regards.
Comment 9 Dattatray Bhat 2010-08-10 06:40:40 UTC
Created attachment 167479 [details] [review]
Patch adding skim reading, navigation by sentence & paragraph

Hi Joanmarie, Alejandro

With your consent, I am working to add the Skim Reading feature. I submitted a patch (ref.comment 8) on 14 July 2010. It seems that you haven't noticed it.

Here is a new patch. It provides Skim Reading, navigation by sentence and navigation by paragraph. Kindly review and comment. I am also working to add Skim Reading Summary and Fast Forward & Reverse during Say All, and will submit a patch soon. Your feedback on the current patch will tell me if I am on the right track.

Regards.

Dattatray Bhat
Comment 10 Joanmarie Diggs (IRC: joanie) 2010-08-10 07:31:50 UTC
Review of attachment 167479 [details] [review]:

1. You modified textLines() in the default script to take an optional SKIMREAD argument. What about the other scripts' implementations of textLines()?

2. Your sentence functionality seems to assume that AtkText sentence boundaries have been implemented by most (if not all) apps and toolkits. Last time I checked, that was not the case. Which means we will have users coming to us complaining that navigation by sentence doesn't work as expected. You need a fallback plan for those apps and toolkits in which the desired boundary is not implemented -- or not implemented as you'd expect.

3. Your sentence functionality seems to be mixing focus tracking mode (for speech) with flat review mode (for braille). You don't want to do that.

4. Why paragraph navigation? I don't believe we have a request for it. (Do we??) OOo Writer has native working paragraph navigation. So do a handful of other apps. And for Gecko apps, Orca already has implemented structural navigation by paragraph. Regardless....

5. Your paragraph functionality seems to assume the presence of RELATION_FLOWS_FROM and RELATION_FLOWS_TO. OpenOffice does, Evolution does, GtkHtml2 does. And undoubtedly a handful of others. However, I believe that you will find that the bulk of other apps and toolkits fail to do so. This will cause your paragraph functionality to fail in many cases.

6. Orca+Right and Orca+Left are already bound in the Gecko script. Therefore your assignments are introducing a conflict with other Orca commands.

7. I'd be interested in hearing the opinions of the community with respect to your chosen keybindings. (Not counting the above issue which needs to be resolved.) In general we tend to be conservative with keybinding assignments. I can imagine there being at least some users who have bound Orca+Up and Orca+Down for other things. So those bindings, too, might not be an ideal choice. 

8. Various and sundry nits with spacing and capitalization and such. Which I won't itemize given the above issues, which are far more pressing.
Comment 11 Dattatray Bhat 2010-08-10 11:32:51 UTC
(In reply to comment #10)
> Review of attachment 167479 [details] [review]:
> 
> 1. You modified textLines() in the default script to take an optional SKIMREAD
> argument. What about the other scripts' implementations of textLines()?

Checked other scripts' implementations of textLines(). They need to be modified to take the additional SKIMREAD argument. I would do it. 

> 2. Your sentence functionality assumes that AtkText sentence boundaries
> have been implemented by most (if not all) apps and toolkits. Last time I
> checked, that was not the case. Which means we will have users coming to us
> complaining that navigation by sentence doesn't work as expected. You need a
> fallback plan for those apps and toolkits in which the desired boundary is not
> implemented -- or not implemented as you'd expect.

Apps and toolkits which do not implement sentence boundaries will need alternate code to identify the boundaries. I would add it. Can you please give some examples of such apps and toolkits? How can one identify such apps? 
   
> 3. Your sentence functionality seems to be mixing focus tracking mode (for
> speech) with flat review mode (for braille). You don't want to do that.

I'm really sorry, but I haven't understood this. Can you make it more clear please?
 
> 4. Why paragraph navigation? I don't believe we have a request for it. (Do
> we??) OOo Writer has native working paragraph navigation. So do a handful of
> other apps. And for Gecko apps, Orca already has implemented structural
> navigation by paragraph. Regardless....
> 5. Your paragraph functionality seems to assume the presence of
> RELATION_FLOWS_FROM and RELATION_FLOWS_TO. OpenOffice does, Evolution does,
> GtkHtml2 does. And undoubtedly a handful of others. However, I believe that
> you will find that the bulk of other apps and toolkits fail to do so. This
> will cause your paragraph functionality to fail in many cases.

My fault. Somehow I thought that OOo Writer didn't provide navigation by paragraph. I was keen on it because a sequence of paragraphs is similar to a sequence of links in the Skim Read Summary. Now I'm convinced that OOo writer provides paragraph navigation and Orca need not worry about it.

> 6. Orca+Right and Orca+Left are already bound in the Gecko script. Therefore
> your assignments are introducing a conflict with other Orca commands.
> 7. I'd be interested in hearing the opinions of the community with respect to
> your chosen keybindings. (Not counting the above issue which needs to be
> resolved.) In general we tend to be conservative with keybinding assignments. 
> I can imagine there being at least some users who have bound Orca+Up and
> Orca+Down for other things. So those bindings, too, might not be an ideal
> choice. 

Agreed. Intended to keep the sentence navigation functions unbound. Assigned fixed key bindings only because Orca2.31.90pre had a problem (which you solved today) with key binding assignment.
 
> 8. Various and sundry nits with spacing and capitalization and such. Which I
> won't itemize given the above issues, which are far more pressing.

I am really obliged for such a detailed review. I would submit a new patch after addressing 1,2,3. Please give some more information regarding my above queries on 2 and 3.

Regards.

Dattatray Bhat
Comment 12 Dattatray Bhat 2010-11-16 09:34:45 UTC
Created attachment 174591 [details] [review]
Orca: Adds the basic skim reading feature.

This patch adds only basic skim read feature. 
 
When user issues the 'Skim Read' command (Ctrl + KP_Add in desktop, Orca + Ctrl + semicolon in laptop), Orca skims through the entire document. It starts at the current line/ sentence, and then reads only the first line/ sentence of each subsequent paragraph. Whether it reads the lines or sentences depends on the Say All By setting.

Skim reading calls the same functions as those called during say all viz.
sayAll() and textLines(). An additional default parameter (SKIMREAD = False)
is added to both the functions, altering their behaviour. When SKIMREAD is
True only the first line/ sentence of each paragraph is spoken.

The patch works for OOo writer, Firefox, Evolution, Thunderbird.

Please test the patch and give your feedback.

Regards.
Comment 13 Dattatray Bhat 2010-11-26 16:46:33 UTC
Created attachment 175316 [details] [review]
Orca: Add Skim Reading to OOo Writer, Firefox, Gedit, Evolution

My last patch (comment 12) left out the Gedit script.

This enhanced patch works with OOo Writer, Firefox, Evolution, Thunderbird, and Gedit. 

Please test the patch and give your feedback.

Regards.
Comment 14 Joanmarie Diggs (IRC: joanie) 2011-01-19 15:53:22 UTC
Hi Dattatray.

As part of the ongoing refactor and creation of a plugin system, there are going to be significant changes in Orca that include a rewrite of sayAll, the addition of caret navigation, and the addition of supporting code. And the changes should make it possible to have a cleaner implementation which allows more options in the skim reading.
Comment 15 Dattatray Bhat 2011-01-20 08:03:43 UTC
Hi Joanie,

Thanks. So, the new patch should fit with and benefit from the coming refactored Orca. Is this applicable only to skim reading patch or to other patches as well?  When is the new Orca likely to be released?

Regards.
Comment 16 Dattatray Bhat 2011-08-10 06:22:30 UTC
Hi Joanie,

What is the current status of activities described in comment 14 please? Is there scope for writing a new patch now to implement Skim Reading?

Regards.
Comment 17 dhairyashil 2013-12-16 08:59:18 UTC
HI  Willie Walker , Joanmarie Diggs ,  Dattatray Bhat ,

I am New To orca , I like to work on Orca .can you help me that I want to understand the code or working of orca . I like to contribute to orca. so please Guide me or help me to understand the working of code of orca.
Comment 18 dhairyashil 2014-09-18 12:07:14 UTC
Created attachment 286482 [details]
Orca SkimRead

Skim Read is very useful feature to quickly navigate or skims through entire document. Reference from Comment 12, we extend the skimRead functionality. The patch was submitted by Dattatray Bhat in Comment13 , it was generated on orca-xdesktop-3.2.0, so its not working on Ubuntu 12 or Gnome 3 interface platforms. So this patch which is based on Orca-3.4.2 which comes with Ubuntu 12 and works with Gnome 3 interfaces. For enhancing skimRead feature we use external python libraries like 'PyUserInput' for generating Fake Key Event. We extends previous skimRead feature by adding following new functionality:

1)  The SkimRead is enhanced by adding new feature. In previous skimRead feature, it  starts reading from current line and then reads first line of subsequent paragraphs. In enhanced skimRead, it starts reading from first line of current paragraph and reads subsequent paragraph's first line. The enhanced skimRead feature gives user to start skimRead from top of document by pressing 't' key . When skimRead is enabled and user press 't' key then skimRead start from top of document. When SkimRead is enabled and user pressed any key then skimRead stops.
2)  The Highlight feature is used for enhancing skimRead feature. When skimRead is enabled , it underline current line. It is useful for partially blind user.  When "Say All By" settings is set to Line then Highlight underline feature works fine.

The Orca-SkimRead archive contains:
----------------------------------

1) Orca-skimRead patch file.
2) Pyatspi patch file.
3) ReadMe file.

Dependency to install orca-skimRead 
----------------------------------- 

1) Install 'python-pip' using 'apt-get install python-pip'. 
2) Install 'PyUserInput' using ' pip install PyUserInput ', or download it 
   from 'https://github.com/SavinaRoja/PyUserInput/archive/master.zip'. 
3) Install 'python-xlib' using Synaptic Package Manager.
Comment 19 Alejandro Piñeiro Iglesias (IRC: infapi00) 2014-09-18 13:36:44 UTC
(In reply to comment #18)
> Created an attachment (id=286482) [details]
> Orca SkimRead

Hi, Im not in place to review the full patch as I'm not an Orca reviewer, but I would like to provide some specific advices about the usual policy providing patches to any GNOME module.


> 
> The Orca-SkimRead archive contains:
> ----------------------------------

Usually new features are not uploaded as tar.gz with several patches. They are uploaded individually. Take into account that bugzilla includes a tool to review patches. Including them on a tar.gz makes that impossible.

> 
> 1) Orca-skimRead patch file.

This should be the only upload. Further explanation below.

> 2) Pyatspi patch file.

This bug was opened against Orca master. By default, it is assumed that you would use orca master and the last stable release of all their dependiences.

That commit (as you mentioned to me privately) is already upstream:
https://git.gnome.org/browse/pyatspi2/commit/?id=6e4dc84d30ff776456290d9b765fb50f73c3d885

And taking into account that is an 2 years old commit, it is clearly included on the last stable release of pyatspi2, so already solved a long time ago. This patch is not needed here.

> 3) ReadMe file.

Usually individual readme files for features are not the way to go. There are two options:
  * If the readme is intended to the reviewer: explain it on bugzilla when the patch is uploaded.
  * If the readme is intended to the user: update the module documentation, so that would means a new patch. To be uploaded individually.


> Dependency to install orca-skimRead 
> ----------------------------------- 
> 
> 1) Install 'python-pip' using 'apt-get install python-pip'. 
> 2) Install 'PyUserInput' using ' pip install PyUserInput ', or download it 
>    from 'https://github.com/SavinaRoja/PyUserInput/archive/master.zip'. 
> 3) Install 'python-xlib' using Synaptic Package Manager.

Managing new dependencies should be part of the patch, and not part of the instructions. Take a look to configure.ac, when the lines AM_CHECK_PYMOD stars.
Comment 20 dhairyashil 2014-09-22 09:23:41 UTC
Created attachment 286789 [details] [review]
Orca-SkimRead-patch

Thanks Alejandro Piñeiro for giving useful comments and I made changes as per your advice.


> The Orca-SkimRead archive contains:
> ----------------------------------
> Usually new features are not uploaded as tar.gz with several patches. They are
> uploaded individually. Take into account that bugzilla includes a tool to
> review patches. Including them on a tar.gz makes that impossible.
> 
> 1) Orca-skimRead patch file.
> This should be the only upload. Further explanation below.


I uploaded separate skimRead patch, please review this patch.


> 2) Pyatspi patch file.
> This bug was opened against Orca master. By default, it is assumed that you
> would use orca master and the last stable release of all their dependiences.
> That commit (as you mentioned to me privately) is already upstream:
> https://git.gnome.org/browse/pyatspi2/commit/?> id=6e4dc84d30ff776456290d9b765fb50f73c3d885
> And taking into account that is an 2 years old commit, it is clearly included
> on the last stable release of pyatspi2, so already solved a long time ago. >This
> patch is not needed here.


This skimRead patch is based on ORCA-3.4.2 version which comes with most of 
Gnome 3 based operating system like ubuntu 12.04, fedora 17, Debian 7. so while working on skimRead feature, I found pyatspi bug, as mentioned by Alejandro Piñeiro the bug was resolved, so for reference I uploaded pyatspi patch. This typo bug of pyatspi is resolved in pyatspi2, but in ubuntu 12.04, fedora 17, Debian 7,  this bug is present in pyatspi, so please consider this issue while reviewing this patch.
 

> Dependency to install orca-skimRead 
> ----------------------------------- 
> 
> 1) Install 'python-pip' using 'apt-get install python-pip'. 
> 2) Install 'PyUserInput' using ' pip install PyUserInput ', or download it 
>    from 'https://github.com/SavinaRoja/PyUserInput/archive/master.zip'. 
> 3) Install 'python-xlib' using Synaptic Package Manager.
> Managing new dependencies should be part of the patch, and not part of the
> instructions. Take a look to configure.ac, when the lines AM_CHECK_PYMOD 
> stars.

Hi Alejandro Piñeiro ,I am working on orca's feature for first time so can you please elaborate in detail about Dependency. I checked configure.ac but I can't understand so please can you explain it in detail.
Comment 21 dhairyashil 2014-09-22 09:27:13 UTC
Created attachment 286791 [details]
ReadMe for SkimRead feature

> ReadMe file.
> Usually individual readme files for features are not the way to go. There are
> two options:
>  * If the readme is intended to the reviewer: explain it on bugzilla when the
> patch is uploaded.
>  * If the readme is intended to the user: update the module documentation, so
> that would means a new patch. To be uploaded individually.

Hi Alejandro Piñeiro, I am uploading ReadMe file separately for skimRead feature. This will be useful for reviewer and for user.
Comment 22 Joanmarie Diggs (IRC: joanie) 2015-11-12 06:59:31 UTC
As an alternative to Skim Read, I added two new Say All features to Orca during the 3.16 release cycle:

* Rewind + Fast Forward
* Structural Navigation

It's not WhatJAWSDoes(tm), but I think it works nicely.

Beyond that, the last release of 3.4.2 was in Spring of 2012. Your patches were a couple of years out of date upon submission. That said, you could certainly try to contribute your patches downstream.