readme

一个小的非常好用的电子书阅读器源码

This is the source code archive for TWReader. It also includes a binary
for 1.1.x snow romdisks.

There are 3 makefiles:

Makefile	for the workstation
agendamake	for the standard Agenda development environment (not
		recently maintained)
snowmake	for the snow Agenda development environment

The agenda makefiles make several versions of the program:

reader		Does Aportis doc, ppm and text files using its own
		fl_file_chooser routine (the standard agenda one 
		doesn't fit the screen)
fltkreader	As above but doesn't use flpda or flek
smlreader	Doesn't do ppm but otherwise like reader
vsmlreader	Doesn't do ppm but does use the Agenda version of
		fl_file_chooser
stdreader	Does ppm and uses the agenda version of fl_file_chooser

stdreader is the one I'd like to distribute but not until fl_file_chooser
works on the Agenda.

The other makefile makes the equivalents to reader and fltkreader in the 
standard agenda makefile.

Upgrading
=========

The .bkmks file produced prior to v1.0 uses a hashdb format file. v1.0 uses
a btree format file to support organising multiple bookmarks per file. The
old .bkmks file should be deleted before starting up the new version. If you
are using any of the 1.0 betas the .bkmks files is compatible and does not
need to be deleted but should be renamed to .twr-bkmks for versions 1.1 and
later.

Whats New in 1.1
================

The major difference is that autogenning is now done in the background
(thanks for the idea, Norman). This means that the progress bar now
appears less obtrusively down in the bottom right hand corner.

The name of the bookmarks files has also changed. Rename your .bkmks file to .twr-bkmks for the new version to pick it up.

I've also added a couple of extra formats. PalmDoc files seem to have
a plethora of minor variants. I'm pretty confident that I can now
handle type 1, very confident of type 2 (which is the only type in the
earlier versions of TWReader) and now, thanks to the bug report from
Bill Kendrick I am moderately confident of being able to handle type
4. Type 4 has bookmarks embedded which I can handle but the only
example of a type 4 file which I have found, these didn't quite line
up - I'm not sure if its me or the file. If you find any files which
TWReader finds embedded bookmarks in, please send them to me
(licensing permitting). Similarly for any other PalmDoc files which
aren't handled correctly - I'm definitely missing the type 3 format!

Also thanks to Bill there is now an icon which you can use. Of course
it'll work with any version but this is the first time I've had it to
include in the tar file.

Whats New in 1.0 (final)
========================

There is a new option on the view menu to select between normal and tight
line spacing. The tight spacing is equivalent to what was used in the past.

The gui has been tweaked and the code has been tightened a little. The main
reader widget (myoutput) IS now a widget so could be included in other apps
much more easily.

I've replaced fl_width with fl_widthi - change it back if you need to compile
against a version of FLTK which doesn't have fl_widthi. Using fl_widthi allows
compilation without the maths libraries - i.e. no floating point. Except
that flek etc require -lm under snow!

As usual, I have fixed all known bugs and incorporated all requested features
with the exception of stuff noted below and the ability to read gzipped files.

Actually, thats a slight lie. I have implemented the ability to read gzipped
files but it needs zlib which is installed in the compilation environment but
wasn't in the romdisk which I have. If you want to try it, or you want to use
it on the workstation, just replace Text.h by ZText.h and add -lz to the link
commands in the makefiles. I'm not sure what the performance or memory usage
will be like on the Agenda - if you do get it working, let me know. 

Whats New in 1.0
================

Intro
-----

All requested features except for scrollbars (I didn't want to lose the
screen space) and landscape display (currently I have no idea where to
start on this - hints welcome) have now been included in TWReader.

The most important bug fixes are handling of words longer than the screen
width - these are now hyphenated and broken across lines, and much
improved location/random access in PalmDoc format files. (Thanks to
Jens Wilhelm Wulf for finding these bugs). Random crashes due to incorrect
structure packing and calling fl_alert inappropriately have also been
fixed (thanks to Eugene Mayevski for setting me down the path to finding
these). Handling of resize events should also now be better should you
pop-up/(whatever the opposite of pop-up is(?)) the keyboard or status
bar while using TWReader.

Bookmarks
---------

Current position can be saved and restored using a user-defined name.
The bookmark named CURRENT is reserved for storing the position in the
file current at program exit. If you have the suspend bug (like me)
then periodically saving the current position to the CURRENT bookmark
will help find the correct location in the file when you next reset the
Agenda.

Bookmarks are accessed via the Marks menu. The menu items are:

Mark - Saves the current position in the bookmark list. You can choose
what ever name you want for it but it defauls to CURRENT. This is the
bookmark loaded at start-up.

Goto - Pops up a list of bookmarks for the current file. Currently,
CURRENT is filtered out but may be put back in if users prefer it
that way. Let me know your preference.

Delete - Pops up the bookmark list and deletes the bookmark selected
by the user.

Autogen - Attempts to guess where bookmarks should be added to the
current file and adds them. The algorithm is very simple - any
paragraphs which end in a letter and are less than 128 characters long
are selected. Make sure you have the format filters (see below) set to
display such paragraphs as you want them. Doing an autogen on a
Project Gutenberg text without StripCR and without Repara results in
almost every line of text going in the bookmarks file.  Hence, USE
THIS WITH CARE! Note that if you have CRs in your file and don't have
StripCR set, nothing goes in.

Clear - Deletes all the bookmarks for the current file.
(Including CURRENT! Save it again if you want it)

Tidy - Deletes all bookmarks which belong to non-existent files.
Unless you want to keep bookmarks for files which you have taken
off the Agenda you should do this every so often to keep the
.bkmks file down to size.

Pageup/down on screen touch
---------------------------

Touching the top/bottom half of the screen results in a Page-up/down.
I'm not sure if I want to keep this feature - I may provide a toggle
to enable people to choose whether or not they want to use it.

Format filters
--------------

Reformatting of input files is now possible using a filter mechanism.
There are currently five filters:

StripCR - removes carriage returns from the text. Useful for DOS and
Project Gutenberg texts. If the other filters don't seem to be working,
turn this on.

Unindent - removes spaces from the first line of a paragraph. Can be
very useful before doing a bookmark Autogen if you don't want spaces
in front of your bookmark names.

Repara - Treats a single LF as a space and a double LF as an end of
paragraph mark.

Indent - Adds an additional indent to the beginning of each paragraph.
Selecting Indent+ from the menu adds two spaces to the indent,
selecting Indent- removes two spaces.

DblSpce - Adds an extra LF between each paragraph. This results in an
empty line between each pair of paragraphs.

Please feel free to suggest more.

Saving/Restoring of Preferences
-------------------------------

The font, font size and whether or not it is bold is remembered
between each invocation of the program. So are the format filters.

Info Screen
-----------

Whilst fixing the bug in location within a PalmDoc file I found that I
could get some extra info regarding file sizes etc. I knocked up a
rudimentary screen to tell you:

Filename - Self explanatory

Filesize - Size of the compressed file

Textsize - Size of the file before compression (approximate in the
case of ppms compressed files)

Ratio % - Compression ratio (approximate in the case of ppms
compressed files). (= 100 - (100*filesize)/textsize)
Higher is better.

Location - Number of characters in the file up to the last currently
displayed (i.e. how much you have read up to that point)

% Read - What percentage of the whole file is represented by Location.

TODO
====

Tidy up the source code. I have a tendency to do put the
implementation in the header files while developing to save swapping
back and forth between .h and .c* files. This needs sorting out.

Similarly, I haven't put much (any?) comments in yet, and what is in
there could be out of date. One day I may get around to correcting
this 8-)

Sort out how to distribute binary versions. There are so many versions
of romdisk out there, each of which is incompatible with different
versions of the compilation environment that it doesn't really make
sense to provide any one. If you can't compile it yourself then let me
know which romdisk you've got and I'll try and provide a version for
you.

Your suggestions. If it doesn't do what you want - let me know and
I'll see what I can do. There are only two things which have been
requested which haven't gone in yet, scrollbars because I don't
want to lose the screen space (if you want them, let me know and
I may reconsider) and rotating the display (because I don't know
how - yet. If you know how and want this feature, let me know).