Reviser v3.0
18th April 1997

Phil Whiles
4 Ivy Cottages
Boyatt Lane
Otterbourne
Winchester
Hants SO21 2HT

philwhiles@poboxes.com
http://www.geocities.com/SiliconValley/Lakes/3216

Contents
	What is Reviser ?
	History
	Registration
	Installation
	Source file format
	Converting existing data
	Test Files
	File locking
	Data Add record
	Data Find and edit
	Data Find and delete
	Config Edit labels
	Config Test
	Config Sound
	Config Graphics
	Config Word wrap
	Start - Q.Field X
	Start - Q.Field Y
	Start - Random
	Start - Clear
	Start - Mark
	Start - Delete
	Start - List
	Special - Export
	Special - Printing
	Marking
	Warranty

What is Reviser ?
-----------------
Reviser is a learning aid which reads
a data file you prepare, and presents
a series of random flash card dialogs,
the first showing a 'question', and the
second showing the 'answer'.

What sets its aside from a simple random
selector is that it can present subsets of
questions from larger sets, provided you
adopt a simple numbering scheme in your
database.

As a test progresses, you get the option to
mark questions which are easy, or that you are
confident about. Once it has asked all the 
questions in the subset, Reviser shuffles up
the unmarked questions and starts the test
again, allowing you to concentrate on the
questions you have difficulty with.

History
-------
Reviser was written to help me in learning Japanese
Vocabulary and Grammar. I had been entering the
vocabulary I had coverered in the course book, into
one large database file on my Psion, so that I could
search the covered vocab. in one file. As I went along,
I recorded the lesson that each word came from in the
book, and a grouping so that Reviser, even in its
earliest form, could select subsets from lessons. 


v1.0	18/12/96 	First Release

v1.1	22/01/97 	Fixed a clear/mark bug
								Added Edit labels
								Added % info summary at start of test
								Added "Are you sure ?" on Esc from test

v1.2	06/02/97	Changed the flash card dialogs
								to use scrollable fields. A side effect
								is that the text is deletable, so a
								"Refresh" button has been added to repaint
								the dialog.

v2.0	19/02/97	Major upgrade. Flash dialogs now
								replaced by graphical display,
								allowing scalable multiline Q.A.'s.
								Added Data - Add record
								Added Data - Find and edit
								Added List view

v2.1	27/02/97	Added Word wrap
								Added saving of misc. config to ini file
								
v2.2	03/03/97	Added "cross-out" of marked entries
								in list view
								Added "isolated" option to Find
v2.3	05/03/97	Improved error handling in 
								conversion routine
v3.0	02/04/97	Added Find and Delete
								Added Start - Delete
								Added Export
								Added Printing

Registration
------------
Reviser is shareware. If you find it useful, and wish
to continue using it, please register. For the
small fee requested, you receive a personal password
which once entered removes the annoying nag screens.

In registering, you encourage the development of even
more quality software for the Psion !

If you provide an email address with your registration
I shall also send you future upgrades to Reviser.

To register send either 10 as either cash
,UK cheque or Eurocheque to the address at the top of this
document. If you send cash, please put it between
two sheets of stiff paper, to disguise it in 
the envelope !

Installation
------------
The following shows where Revisers files need to be
installed. To help you get the hang of the source
file format, (described later), I have included my
own Japanese Language database, and the associated
tests, marked in the following list with an '@' :

\APP\						REVISER.OPA (the executable)

\APP\REVISER\		REVISER.PIC (the graphic)
								REVISER.RSC (optional help)

\OPD\						REVISER.REG (once registered)

\DAT\					@	NIHONGO.DBF (source data)

\TST\					@	*.TST (test files)

Source file format
------------------
Reviser reads a standard Data file that you
provide, but that file must have the following
format :

Field   Desc.     Example
-----   ------    ----------
  1     Mark      0 (or 1)
  2     Lesson    4
  3     Group     2
  4     Field X   Hello
  5     Field Y   Bonjour

Reviser scans the file for records that are not
marked (0), falling within the lesson and group
range specified under Config - Test. It then
shuffles all those up (in memory) and randomly
selects questions, presenting either 'field X' or
'field Y' as the question followed by the
corresponding answer ('field Y' or 'field X').

It can either be set to always use 'field X' as the
question, or 'field Y', or it can choose either on a 
random basis. (See the Start menu)

Because the fields in the Psion Database application
are all strings, if you want to be able to sort 
your source file into lesson/group order, say with
JBDATA, or if you want Reviser to be able to select
subsets properly ie a range of questions, give some
thought to how strings are compared :

ie string "2" is greater than "199" ,
so a group range of "1" to "199" does
not include "2".

Converting existing data
------------------------
To allow you to get your data into Revisers format
there is a Data Conversion menu option under File.
This will take a simple database file having only
two fields, field X and field Y, and convert it
into the 5 field format required by Reviser.

To simplify the job, you may enter defaults for
the mark,lesson and group fields, and choose
either an automatic mode, where each record uses
these defaults, or an interactive one, where you
may elect to overide these defaults on a per
record basis. If you have a source data file having
more than two fields, I will be glad to convert it 
for you !

Test Files
----------
The files that Reviser creates and which appear
under its icon on the system screen, are the
'test' files. When a test file is first created,
you provide the name and location of the test's
source data file, and the labels you wish to be
associated with 'field X' and 'field Y'.

 ie 'English' and 'French'.

Reviser uses these labels when asking it's questions.
The test config is also saved as part of the test
file, which by default includes all questions in the
source file.

To setup a test to have different test config
change it's config (Config-Test), then
Save (File-Save).

File locking
------------
Reviser is a type 3 application, that is it is
possible to have multiple copies of reviser 
running. However, because two tests may read
the same source data file, there is the restriction
that if one Reviser is currently testing or listing
any other Reviser running using the same source
file will be unable to add or find/edit.

Data - Add record
-----------------
Allows you to add new records to the current test
data source file. This means that you do not have
to exit Reviser, start Data/JBData, add the record,
exit Data, and restart Reviser !

Data - Find and edit
--------------------
This accomplishes several tasks ! By finding and 
displaying each match to a find, you get to :

- view each match
- edit and save each match

Find options available are illustrated thus:

Search for:	ie this

Positioned:	Start of line		ie this thing
						Anywhere				ie with this thing
						End of line			ie and this

Within field:	Mark
							Lesson
							Group
							Field X
							Field Y
							All
													
Case sensitive:	Yes
								No

Once the first match is found, you get the option
to edit and save the matched record, after which
the next match is displayed etd etc or simply
view the next match etc etc.

Data - Find and delete
----------------------
The same as Find and edit, except instead of the option
to save, you get to delete records which match the find.
Why ? because you can only have 3 buttons in a dialog
and Find and save used up all 3 !!

Config - saving
---------------
Note that test related config (Labels and Test) are
saved as part of the test file, while other config
is saved in \opd\reviser.ini, and is loaded for all
tests.

Config - Edit labels
--------------------
Allows you to edit the labels used for the question
and answer texts. These will be saved with the test
configuration when File - Save is used.

Config - Test
-------------
Reviser allows a type of specialisation
in its question selection, in that it can
select questions from subsets within 
subsets of questions.

ie each question/answer in the data file
you prepare for Reviser, has two fields
indicating the lesson and grouping/type of
question that it is.

If you do not wish to make use of this 
feature dont worry, simply mark each
question as being in lesson 1 group 1,
and make sure that Reviser is configured
to select using those criteria. 

Config - Sound
--------------
Reviser will give two differently pitched
beeps if Sound is on, one on a question, and
the other on the answer.


Config - Graphics
-----------------
When graphics is on, Reviser shows a graphical
progress bar when it generates an index of your
database at the start of the test sequence.

It will also show a similar graphic when it
shuffles a test having more than 50 matches.

When graphics is off, a simple 'busy' type message
is displayed, taking less time to get a test started.

Config - Word wrap
------------------
When Word wrap is ON, the Q.and A. text wll word
wrap at the end of each line.

When OFF it will spill over in the middle of a word.

You may want to switch it OFF if your text is long,
as wrapping means less displayed text.


Start - Q.Field X
---------------------
The database will be indexed and the test sequence
started with questions being 'field X' and answers
being 'field Y'. ie would allow you to test your 
translation of English to French.
(The menu doesn't show 'field X' or 'field Y' but uses
the labels that you gave when the test file was
created.)

Start - Q.Field Y
---------------------
The database will be indexed and the test sequence
started with questions being 'field Y' and answers
being 'field X'. ie would allow you to test your 
translation of French to English.

Start - Random
--------------
The database will be indexed and the test sequence
started with questions and answers being of mixed
types ie Question in English or French.

Start - Clear
-------------
Will clear the Mark field in all the records in
the current database, matching the current Test
Configuration criteria. These question will then
get asked on subsequent test runs.

Start - Mark
------------
Will set the Mark field in all the records in
the current database, matching the current Test
Configuration criteria. These question will then
not get asked on subsequent test runs.

Start - Delete
--------------
Deletes _all_ records which match the current test
criteria. You are given two chances to quit before
the deletion starts, so don't say I didn't warn you !
Could be of use if you wish to purge your data file
of unwanted test data. Note the test file will still
exist, but Reviser would fail to find any questions
next time you run the test, unless you enter new data.

Start - List
------------
Picks out test matches but rather than testing
you on them, presents a simple list view for
use as a study/revision aid. Currently limited
to displaying a truncated list of Q.and A.'s,
ie not scalable/scrollable if the text is too wide.

Very useful for reviewing the data reviser will pick
out for a test.

Note that the ability to page the list is reserved for
registered users.

Special - Export
----------------
Allows you to export all records which match the current test
criteria to a text file (\opd\reviser.exp). This file
has the following format :

Field X{delimiter}Field Y
Field X{delimiter}Field Y
etc

Where {delimiter} can be one of either comma,colon,
semicolon or hash. This text file can then be merged
into Data, or Brought into Sheet.

Special - Printing
------------------
Print, Print Setup and Print Preview all offer
standard Psion dialogs and functionality for printing
records which match the current test criteria.

There is an extra set of options which allow you
to control the appearance on the printed page :

Single or Multi (2) column layout
Column Width (20..120)
Print Labels (yes/no)

If you choose multi column layout the layout is :

field x : field y
field x : field y
etc

The column size determines the truncation point
of each fields text. (If you choose a large font,
don't set a large colmumn size ...)
Also be sure to choose a fixed width font such as 
courier otherwise column layout goes wrong. (This
is a shortcoming of accessing built in Print routines
from OPL)

if single column :

field x
field y
field x
etc


Marking
-------
Once a test sequence has been started, 
with each answer you get 3 choices for
marking of that particular Q/A :

o None
o Memory
o File

Once all questions in a test have been
asked, Reviser shuffles up its test
index and starts again.

None means ask this question again next
time round.

Memory means mark this question in memory
only and dont ask it next time round
(in this 'loop', ie next time the test
is loaded it will still get asked again)

File means mark the question in the source
file such that it wont get asked again,
even when the test is reloaded.

Warranty
--------
You get absolutely none what so ever !

The author holds no responsibility for this
software, and you use it at your own risk.

(I'll take credit for Grade A exam results though :-)



