Read: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
(64 intermediate revisions by 28 users not shown)
Line 1: Line 1:
{{Activity migrated to sl.o
| download=http://activities.sugarlabs.org/en-US/sugar/addon/4028
| git=http://git.sugarlabs.org/projects/read
}}

{{Translations}}
{{Translations}}


{{Olpcboxtop|toptext=[[{{PAGENAME}}|Read]]}}
{{Olpcboxtop|toptext=[[{{PAGENAME}}|Read]]}}
{{ OBX activity |[[Image:Activity-activity-read.svg]]|core|Version 23 }}
{{ OBX activity |[[Image:Activity-activity-read.svg]]|core}}
{{ OBX source dev|projects/read-activity}}
{{ OBX test |[[Tests/Read|Read]]<!--|2007-09-18--> }}
{{ OBX test |[[Tests/Read|Read]]<!--|2007-09-18--> }}
{{ OBX devtickets |read-activity}}
{{ OBX devtickets |read-activity}}
{{ OBX team |[[User:Morgs|Morgan Collett]], Manusheel Gupta, Marco Gritti, Tomeu Vizoso, [[User:Walter|Walter Bender]] (Adviser), Dan Williams, [[User:Eben|Eben Eliason]], [[User:Rwh|Reinier Heeres]]}}
{{ OBX pootle|1=http://dev.laptop.org/git?p=projects/read-activity;a=blob_plain;f=po/xbook.pot;hb=HEAD|2=xocore}}
{{ OBX mimetypes |application|pdf|image|vnd.djvu|image|x.djvu|image|tiff }}
{{ OBX team |Manusheel Gupta, Marco Gritti, Tomeu Vizoso, [[User:Walter|Walter Bender]] (Advisor), Dan Williams, [[User:Eben|Eben Eliason]]}}
{{ OBX mimetypes |application|pdf }}
<small>see more [[:Category:OBX templates|templates]] or [[OBX proposals|propose new]]</small>
<small>see more [[:Category:OBX templates|templates]] or [[OBX proposals|propose new]]</small>
{{Olpcboxbottom}}
{{Olpcboxbottom}}


{{Users}}
==Description & Goals==


==Description & Goals==
{{Users}}
[[Image:activity_read.jpg|right|thumb|Read activity]]
[[Image:activity_read.jpg|right|thumb|Read activity]]


===Summary===
===Summary===


The Read activity allows the laptop to act as a book reader. It has a simple interface, and will view many kinds of text and image based book-like materials (PDF files work currenty). It will have particular strengths in Handheld mode, with extremely low power consumption and simple navigation controls.
The Read activity allows the laptop to act as a book reader. It has a simple interface, and will view many kinds of text and image-based book-like materials. It will have particular strengths in handheld mode, with extremely low power consumption and simple navigation controls.


It can currently read PDF files successfully.
Read can read PDF files and single-page TIFF files.
Version 42 and higher of Read, in conjunction with supporting libraries, can also read [[DJVU]] files (see bug {{Ticket|6223}}).


== Sources of free books ==
Note that '''the Read activity is launched from the Journal''': you "resume" PDFs that you have downloaded via the Browser or loaded via a USB memory stick.

This wiki includes a page devoted to electronic-format ("e-")[[Books]].

[http://books.google.com/ Google Book Search 'Beta'] provides millions of books, and most (if not nearly all?) of the books out of copyright (i.e. [http://books.google.com/books?as_q=&num=100&btnG=Google+Search&as_epq=&as_oq=&as_eq=&as_libcat=0&as_brr=1&lr=&as_vt=&as_auth=&as_pub=&as_sub=&as_drrb=c&as_miny=1&as_maxy=1922&as_isbn= pre-1923CE in USA] ) can be downloaded as Adobe Acrobat (".pdf") files which Read can display. One such book (18.9MB) is [http://books.google.com/books?id=siPZKHPQ1rcC <i>A History of Cambridge, Massachusetts, 1630-1913</i>] - [[User:Docdtv|Docdtv]] 17:07, 23 March 2008 (EDT)

You can also encapsulate in PDF format any new free book that you create with Microsoft Windows authoring application programs by using the free
tool [http://sourceforge.net/projects/pdfcreator/ PDFCreator]. When you do so, don't forget to include a [http://creativecommons.org/licenses/ Creative Commons License] and publish your book in a well-known archive, e.g. [http://www.archive.org/details/texts The Internet Archive]. (The Internet Archive also provides content in the Djvu format which Read will ultimately support.) - [[User:Docdtv|Docdtv]] 18:00, 23 March 2008 (EDT)

A selection of out-of-copyright books in PDF format is available at [http://www.gutenberg.org/catalog/world/results?lang=en&filetype=pdf&pageno=1 Project Gutenberg with this search].

Other Project Gutenberg texts can be converted to PDFs and downloaded at [http://manybooks.net/ ManyBooks.net].

== How to use ==

The Read activity is launched by opening the [[Journal]], choosing a PDF document, and "resuming" it. This will cause the Read activity to open automatically. PDFs downloaded from [[Browse]] can be opened in this way, as can PDFs on an [http://wiki.laptop.org/go/Journal#External_storage_devices external storage device].

='''Keyboard navigation'''=

First make sure the document canvas is selected (and not the tool-bar menu) by clicking either in the page area, or pressing the TAB key until focus moves out of the toolbar (2 presses usually):

* Keyboard cursors, or screen direction pad, will scroll the page a few lines in any direction
* ALT + keyboard cursors, or screen direction pad, will scroll the page a small amount in any direction
* FN + keyboard cursor up/down will move one page up or down (with a small overlap to keep context)
* Screen gamepad buttons circle and cross also act as page up and page down (with a small overlap to keep context)
* Screen gamepad buttons square and tick act as a zoom in and zoom out
* FN + keyboard cursor right/left will jump to the start or end of the document
* For vi fans (a Terminal based text editor), keys h, j, k, l also act as left, down, up, right

=== Full screen mode ===

To use the reader in full screen mode, press '''ALT+Enter''' together. All the icons and text around the border will disappear, leaving you with only the document on screen. To get back to normal, press '''ALT+Enter''' again. Hopefully this might become an on screen icon option one day(?)


{{Developers}}
{{Developers}}

===Source===
===Source===


Line 32: Line 68:
===Executable .xo files===
===Executable .xo files===


See the form at the bottom of this page for a link to the .xo bundle.
* [[Image:Read-32.xo]] v.35



Currently the activity has to be opened from the Journal; PDF functionality works, but the activity is memory hungry. I couldn`t open any other file types (.txt .htm .djvu for example didn`t work). --[[User:Tomhannen|Tomhannen]] 15:33, 8 December 2007 (EST)
Currently the activity has to be opened from the Journal; PDF functionality works, but the activity is memory hungry. I couldn`t open any other file types (.txt .htm .djvu for example didn`t work). --[[User:Tomhannen|Tomhannen]] 15:33, 8 December 2007 (EST)
Line 67: Line 104:
=Development=
=Development=


=====[[Talk:Read#Feature Requests|Feature Requests]]=====
====[[Talk:Read#Feature Requests|Feature Requests]]====
''Add Feature Requests to this page's [[Talk:Read#Feature Requests|Talk page]] (click the "discussion" tab), don't put them here.''

* Read needs some sort of word wrap option - when you zoom beyond page width, it should be possible to still view all text wrapped around more lines.
*: Unfortunately unlikely to happen. That's extremely hard to do for PDF files and similar media types that are designed to exactly represent a page layout. (There's an advanced PDF feature for reflowing, but the documents need to be built with support for that and hardly any do.) If you want re-flowed text, I recommend HTML and the "browse" activity, and reflowable media such as RTF files could be converted to HTML.[[User:Kweidner|Kweidner]] 01:16, 27 January 2008 (EST)
*: What is wrong is using PDF as a primary format for a simple e-book. Txt/ASCII/Unicode e-books don't have that problem, or shouldn't have that problem if the reading software actually works. :[[User:Tinktron|Tinktron]] 02:03, 19 June 2008 (EDT)


* After a few seconds, the mouse cursor should disappear - it is distracting while reading.

* There should be a simple way to hide the whole interface, leaving only the text on screen. This could be more useful than the "jump to end, jump to start" hot keys currently assigned to the game buttons.

* This last one may be a Sugar issue, not a Read issue, but I`ll mention it anyway: The rotation key by the screen causes the track-pad to behave confusingly when in portrait mode. Also, some thought should go into the rotation process - I am left handed, but would rather only have two possible orientations to deal with when rotating - portrait or landscape are all that is required - not 4 options at each 90 degree rotation.
--[[User:Tomhannen|Tomhannen]] 07:41, 23 December 2007 (EST)

* OTOH, I find having all 4 orientations useful as it makes it easier to use the XO in some situations, particularly the 2 portrait options. But I do agree about the trackpad and button orientation issues.
--[[User:Jdougan|Jdougan]] 02:13, 25 December 2007 (EST)

* Another vote for the Track pad and orientation issues. That's happened to me as well

* Everyone agrees that when documents are rotated in the display, any directional movement controls should change meaning to maintain parallelism. But I would add something more. The two sets of game controls provide a total of eight buttons. The Read Activity should use one set of four buttons for panning WITHIN a page and the other set of four for both (a) zooming in and out WITHIN the page and (b) moving forward and backward BETWEEN (adjacent) document pages. This is vital for e-book configuration of the display panel to be PRACTICAL. - [[User:Docdtv|Docdtv]] 00:20, 24 March 2008 (EDT)

* Also I see a lot of .pdf'd versions of texts with very wide margins on the pages. This is a reflection of the physical printing where at the final stages the pages are trimmed to create even edges. "Zoom to Width" sets a scale that covers the whole page, margins included, making allot of blank screen space and small text. The other option is to manually set the scale of the page. Thats awkward if you have the screen folded use the XO as a tablet reader. It would be useful to have an option/button that automatically zooms the user to the width of the printed text("Zoom to margin"?).

* Allow Journal to resume from an SD card with the last page being read as the starting page once resumed.


* The left mouse button seems to do a page forward when the screen is rotated for ebook mode. Strangely enough, it doesn't do this when the screen is in the normal orientation. The problem with this is that when I have the display rotated in tablet mode and squeeze the display and keyboard together (easy to do when reading) the page jumps forward several times. This makes it frustrating to read in ebook mode.
--[[User:Jdsimmons|Jdsimmons]] 02:52, 5 January 2008 (CST)

* Is there any way when in full-screen rotated mode, to page through an ebook a page at a time? Game keys only move a line at a time for me.

* Have a quick boot for ebook, where only items needed to run ebook are loaded. Having a boot time of say 10 seconds as Asus eee does instead of 2 minutes would make the ebook function far more usable.
*This would be an interesting feature, or having an XO hibernate mode that returned into read activity where stopped.

* All files should open in Fit-to-width zoom mode by default. Also, Read should "re-zoom" to fit to width on rotate.

* The reader should be able to handle plain ASCII text files (like Gutenberg etexts) without having to go through manybooks.net conversion. One acceptible technique to render text as .PDF in 80-column 63-line is as follows:
cat filename.txt | a2ps --no-header -1 --borders=0 -o filename.ps ; ps2pdf filename.ps filename.pdf

=====[[Talk:Read#Implementation Discussion|Implementation Discussion]]=====
=====[[Talk:Read#Implementation Discussion|Implementation Discussion]]=====
=====[[Read/Versions|Version History]]=====
=====[[Read/Versions|Version History]]=====



=Functional Test=
=Functional Test=
Line 81: Line 156:
*Ensure that the image rotates with the rotate button and continues to scroll with the gamepad keys.
*Ensure that the image rotates with the rotate button and continues to scroll with the gamepad keys.
*Ensure that zoom works: change the zoom 'Zoom to fit', 'Zoom to width' and 'Actual size', use the zoom controls to zoom to 95% and then 150%
*Ensure that zoom works: change the zoom 'Zoom to fit', 'Zoom to width' and 'Actual size', use the zoom controls to zoom to 95% and then 150%
*Ensure next/previous page work; stay on a page other than page 1.
*Ensure next/previous page work; start on a page other than page 1.
*Close the activity; ensure that it closes properly.
*Close the activity; ensure that it closes properly.
*Resume the activity from the Journal
*Resume the activity from the Journal
Line 104: Line 179:
[[Category:Developers]]
[[Category:Developers]]
[[Category:Sugar]]
[[Category:Sugar]]
{{Activity page
|icon=Image:Activity-activity-read.svg
|genre=Documents (Read, Write, and Share)
|activity group=Activities/G1G1
|short description=A document reader.
|long description=A document reader for the XO that can read Ebooks as well as standard pdf's and single page tiffs.
|contact person=User:Morgs
|activity source=http://git.sugarlabs.org/projects/read/repos/mainline
|language codes=af, am, ar, ay, bg, bn, ca, de, dz, el, en, es, fa, ff, fr, gu, ha, hi, ht, ig, is, it, ja, km, ko, mk, ml, mn, mr, nb, ne, nl, pa, pl, ps, pt, qu, ro, ru, rw, sd, si, sl, te, th, tr, ur, vi, yo, zh
|i18n=https://dev.laptop.org/translate/projects/fructose82/
|bundle URL=http://dev.laptop.org/~morgan/bundles/Read-52.xo
|activity version=52
|releases=8.2.0 (767), Candidate
|devel status=5. Production-stable
}}
{{Activity bundle
|bundle URL=http://dev.laptop.org/~morgan/bundles/Read-61.xo
|activity version=61
|devel status=3. Alpha
}}

Latest revision as of 16:08, 9 April 2012

?Sugar icon}}    This activity is now hosted at the Sugar Activity Library.

The information here is likely to be out-of-date. Consult the new pages for "Read" first:

  Please copy/paste "{{Translationlist | xx | origlang=en | translated={{{translated}}}}}" (where xx is ISO 639 language code for your translation) to Read/translations HowTo [ID# 269155]  +/-  


Activity-activity-read.svg This activity was core
TST Read
Trac print.png Tickets all - active - new
OlpcProject.png Morgan Collett, Manusheel Gupta, Marco Gritti, Tomeu Vizoso, Walter Bender (Adviser), Dan Williams, Eben Eliason, Reinier Heeres

see more templates or propose new


Description & Goals

  For the general public
Read activity

Summary

The Read activity allows the laptop to act as a book reader. It has a simple interface, and will view many kinds of text and image-based book-like materials. It will have particular strengths in handheld mode, with extremely low power consumption and simple navigation controls.

Read can read PDF files and single-page TIFF files. Version 42 and higher of Read, in conjunction with supporting libraries, can also read DJVU files (see bug #6223).

Sources of free books

This wiki includes a page devoted to electronic-format ("e-")Books.

Google Book Search 'Beta' provides millions of books, and most (if not nearly all?) of the books out of copyright (i.e. pre-1923CE in USA ) can be downloaded as Adobe Acrobat (".pdf") files which Read can display. One such book (18.9MB) is A History of Cambridge, Massachusetts, 1630-1913 - Docdtv 17:07, 23 March 2008 (EDT)

You can also encapsulate in PDF format any new free book that you create with Microsoft Windows authoring application programs by using the free tool PDFCreator. When you do so, don't forget to include a Creative Commons License and publish your book in a well-known archive, e.g. The Internet Archive. (The Internet Archive also provides content in the Djvu format which Read will ultimately support.) - Docdtv 18:00, 23 March 2008 (EDT)

A selection of out-of-copyright books in PDF format is available at Project Gutenberg with this search.

Other Project Gutenberg texts can be converted to PDFs and downloaded at ManyBooks.net.

How to use

The Read activity is launched by opening the Journal, choosing a PDF document, and "resuming" it. This will cause the Read activity to open automatically. PDFs downloaded from Browse can be opened in this way, as can PDFs on an external storage device.

Keyboard navigation

First make sure the document canvas is selected (and not the tool-bar menu) by clicking either in the page area, or pressing the TAB key until focus moves out of the toolbar (2 presses usually):

  • Keyboard cursors, or screen direction pad, will scroll the page a few lines in any direction
  • ALT + keyboard cursors, or screen direction pad, will scroll the page a small amount in any direction
  • FN + keyboard cursor up/down will move one page up or down (with a small overlap to keep context)
  • Screen gamepad buttons circle and cross also act as page up and page down (with a small overlap to keep context)
  • Screen gamepad buttons square and tick act as a zoom in and zoom out
  • FN + keyboard cursor right/left will jump to the start or end of the document
  • For vi fans (a Terminal based text editor), keys h, j, k, l also act as left, down, up, right

Full screen mode

To use the reader in full screen mode, press ALT+Enter together. All the icons and text around the border will disappear, leaving you with only the document on screen. To get back to normal, press ALT+Enter again. Hopefully this might become an on screen icon option one day(?)


Source

http://dev.laptop.org/git.do?p=projects/read-activity

Executable .xo files

See the form at the bottom of this page for a link to the .xo bundle.


Currently the activity has to be opened from the Journal; PDF functionality works, but the activity is memory hungry. I couldn`t open any other file types (.txt .htm .djvu for example didn`t work). --Tomhannen 15:33, 8 December 2007 (EST)

This worked like a charm, my first experience with Sugar beyond the main applications. Very clever. Thanks to Tomhannen. Very readable with almost dark screen. Loading time is excessive as you page ahead. But it works great and will likely bring on lots of Memory Full problems as PDF files of Encyclopedia Britannica become available in Tanzania. 8-) --W9ZSJ 22 December 2007

How to install the Read activity

  • To use the reader, download the .xo file shown above, using the Browse activity.
  • When it has downloaded, save it to your Journal.
  • Go to your Journal, click on the Read.xo activity, and choose "Resume".
  • The read activity should now be installed.

Media to try on the reader

  • To read a document, download the document to your Journal, then Resume it using the Read activity.
  • A large (14MB) PDF file with illustrations can be found [here].
  • It viewed correctly on a B4 laptop with OS build 650.

Screenshots

Find functionality
Navigation
Zooming
Dynamic Table of Contents

Development

Feature Requests

Add Feature Requests to this page's Talk page (click the "discussion" tab), don't put them here.

  • Read needs some sort of word wrap option - when you zoom beyond page width, it should be possible to still view all text wrapped around more lines.
    Unfortunately unlikely to happen. That's extremely hard to do for PDF files and similar media types that are designed to exactly represent a page layout. (There's an advanced PDF feature for reflowing, but the documents need to be built with support for that and hardly any do.) If you want re-flowed text, I recommend HTML and the "browse" activity, and reflowable media such as RTF files could be converted to HTML.Kweidner 01:16, 27 January 2008 (EST)
    What is wrong is using PDF as a primary format for a simple e-book. Txt/ASCII/Unicode e-books don't have that problem, or shouldn't have that problem if the reading software actually works. :Tinktron 02:03, 19 June 2008 (EDT)


  • After a few seconds, the mouse cursor should disappear - it is distracting while reading.
  • There should be a simple way to hide the whole interface, leaving only the text on screen. This could be more useful than the "jump to end, jump to start" hot keys currently assigned to the game buttons.
  • This last one may be a Sugar issue, not a Read issue, but I`ll mention it anyway: The rotation key by the screen causes the track-pad to behave confusingly when in portrait mode. Also, some thought should go into the rotation process - I am left handed, but would rather only have two possible orientations to deal with when rotating - portrait or landscape are all that is required - not 4 options at each 90 degree rotation.

--Tomhannen 07:41, 23 December 2007 (EST)

  • OTOH, I find having all 4 orientations useful as it makes it easier to use the XO in some situations, particularly the 2 portrait options. But I do agree about the trackpad and button orientation issues.

--Jdougan 02:13, 25 December 2007 (EST)

  • Another vote for the Track pad and orientation issues. That's happened to me as well
  • Everyone agrees that when documents are rotated in the display, any directional movement controls should change meaning to maintain parallelism. But I would add something more. The two sets of game controls provide a total of eight buttons. The Read Activity should use one set of four buttons for panning WITHIN a page and the other set of four for both (a) zooming in and out WITHIN the page and (b) moving forward and backward BETWEEN (adjacent) document pages. This is vital for e-book configuration of the display panel to be PRACTICAL. - Docdtv 00:20, 24 March 2008 (EDT)
  • Also I see a lot of .pdf'd versions of texts with very wide margins on the pages. This is a reflection of the physical printing where at the final stages the pages are trimmed to create even edges. "Zoom to Width" sets a scale that covers the whole page, margins included, making allot of blank screen space and small text. The other option is to manually set the scale of the page. Thats awkward if you have the screen folded use the XO as a tablet reader. It would be useful to have an option/button that automatically zooms the user to the width of the printed text("Zoom to margin"?).
  • Allow Journal to resume from an SD card with the last page being read as the starting page once resumed.


  • The left mouse button seems to do a page forward when the screen is rotated for ebook mode. Strangely enough, it doesn't do this when the screen is in the normal orientation. The problem with this is that when I have the display rotated in tablet mode and squeeze the display and keyboard together (easy to do when reading) the page jumps forward several times. This makes it frustrating to read in ebook mode.

--Jdsimmons 02:52, 5 January 2008 (CST)

  • Is there any way when in full-screen rotated mode, to page through an ebook a page at a time? Game keys only move a line at a time for me.
  • Have a quick boot for ebook, where only items needed to run ebook are loaded. Having a boot time of say 10 seconds as Asus eee does instead of 2 minutes would make the ebook function far more usable.
 *This would be an interesting feature, or having an XO hibernate mode that returned into read activity where stopped.
  • All files should open in Fit-to-width zoom mode by default. Also, Read should "re-zoom" to fit to width on rotate.
  • The reader should be able to handle plain ASCII text files (like Gutenberg etexts) without having to go through manybooks.net conversion. One acceptible technique to render text as .PDF in 80-column 63-line is as follows:
 cat filename.txt | a2ps --no-header -1 --borders=0 -o filename.ps ; ps2pdf filename.ps filename.pdf
Implementation Discussion
Version History

Functional Test

Basic

  • Open the browser window and go to the library or content url (not sure exactly how this will work yet).
  • Double click on a book from the library directory.
  • Ensure that the file scrolls properly using the scroll keys and the up/down arrow keys.
  • Ensure that the image rotates with the rotate button and continues to scroll with the gamepad keys.
  • Ensure that zoom works: change the zoom 'Zoom to fit', 'Zoom to width' and 'Actual size', use the zoom controls to zoom to 95% and then 150%
  • Ensure next/previous page work; start on a page other than page 1.
  • Close the activity; ensure that it closes properly.
  • Resume the activity from the Journal
  • Check that the page number and the zoom level are still what they were before closing (The page position may not be exactly the same as before, but should be on the same page number).

Secondary

  • Share the book with another XO.
  • Ensure that both people can read the book.

Initial mockups of the Reader

Document Description
Activity Mockup (2MB) history Adobe Illustrator file containing mockups for each toolbar


Activity Summary

Icon: Sugar icon::Image:Activity-activity-read.svg
Genre: Activity genre::Documents (Read, Write, and Share)
Activity group: ,|x|Activity group::x}}
Short description: Short description::A document reader.
Description: Description::A document reader for the XO that can read Ebooks as well as standard pdf's and single page tiffs.
Maintainers: ,|x|Contact person::x}}
Repository URL: Source code::http://git.sugarlabs.org/projects/read/repos/mainline
Available languages: ,|x|Available languages::x}}
Available languages (codes): ,|x|Language code::x}}
Pootle URL: Localization URL::https://dev.laptop.org/translate/projects/fructose82/
Related projects: Related projects,|x|Related projects::x}}
Contributors: ,|x|Team member::x}}
URL from which to download the latest .xo bundle Activity bundle::http://dev.laptop.org/~morgan/bundles/Read-52.xo
Last tested version number: Activity version::52
The releases with which this version of the activity has been tested. ,|x|Software release::x}}
Development status: Devel status::5. Production-stable
Ready for testing (development has progressed to the point where testers should try it out): ,|x|Ready for testing::x}}
smoke tested :
test plan available :
test plan executed :
developer response to testing :


URL from which to download the last .xo bundle that works with old releases Activity bundle::http://dev.laptop.org/~morgan/bundles/Read-61.xo
Activity version number: Activity version::61
The releases with which this version of the activity has been tested. ,|x|Software release::x}}
Development status: Devel status::3. Alpha