Reviser v3.2
1st September 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
	Display
	Source file format
	Converting existing data
	Test Files
	File locking
	Data - New Source
	Data - Switch Source
	Data - Add record
	Data - Find and edit
	Data - Find and delete
	Config - Test comments
	Config - Test labels
	Config - Test includes
	Config - Test excludes
	Config - Sound
	Config - Graphics
	Config - Word wrap
	Marking
	Editing within a test
	Start - Q.Field X
	Start - Q.Field Y
	Start - Random
	Start - Clear
	Start - Mark
	Start - Delete
	Start - List
	Special - Export
	Special - Printing
	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
v3.1	04/08/97	Test config became Test includes
								and Test excludes added.
								Can now escape from indexing
								Test comments added.
								Data - New Source added.
								Data - Switch Source added.
								Fixed a bug in Data - Add record
v3.2  01/09/97	Added editing of records within a test
								Added 'speed keys' to Answer dialog
								Changed the summary/statistics window to
								be a custom dialog
	
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 10 as either cash
,UK cheque or Eurocheque to the address at the top of this
text. 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 an
example database, geogrphy.dbf, 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)
								REVISER.INI (once run)
								
\DAT\					@	GEOGRPHY.DBF (source data)

\TST\					@	*.TST (test files)



Display
-------
Once you have installed and started Reviser it
will display a background of "?" icons, and show
a status line at the bottom of the screen.
The status line shows (in left to right order) :

a. The current test file name. If the test has
had its config changed and needs saving, the
test file name will be shown in inverse. ie white
on black.

b. The current tests data source file name.

c. The test includes :

	 min. lesson
	 max. lesson
	 min. group
	 max. group
	 
	 ie 100:110:1:4
	 
	 If test excludes (see later) have been set, an 
	 X will appear after the test includes to remind 
	 you.

d. Registration status.

The main display has a menu attached from which
all of revisers functions can be accessed.

Note: once a test is in progress, or while in list
mode, the main menu is inaccessable as the functions
no longer apply.

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 includes.
(and discards those that fall within the Test
excludes)

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".

The sample geogrphy.dbf and its tests show how to
arrange records in such a way that the maximum test
flexibility can be had. The database contains 3 types
of data records for each country, with countries 
arranged in groups according to location :

(mark:lesson:group:field x:field y)
	
0,	100,	100,	Germany - capital,	Berlin
0,	200,	100,	Germany - currency,	deutsche mark
0,	300,	100,	Germany - food,	bratwurst
0,	100,	101,	UK - capital,	London
0,	200,	101,	UK - currency,	pound
0,	300,	101,	UK - food,	fish and chips
0,	100,	102,	France - capital,	Paris
0,	200,	102,	France - currency,	franc
0,	300,	103,	France - food,	garlic
0,	100,	103,	Spain - capital,	Madrid
0,	200,	103,	Spain - currency,	peseta
0,	300,	103,	Spain - food,	olives
0,	100,	104,	Belgium - capital,	Brussells
0,	200,	104,	Belgium - currency,	franc
0,	300,	104,	Belgium - food,	praline
0,	100,	200,	Thailand - capital,	Bangkok
0,	200,	200,	Thailand - currency,	baht
0,	300,	200,	Thailand - food,	fish curry
0,	100,	201,	China - capital,	Beijing
0,	200,	201,	China - currency,	yuan
0,	300,	201,	China - food,	rice
0,	100,	202,	Malaysia - capital,	Kuala Lumpur
0,	200,	202,	Malaysia - currency,	ringgit
0,	300,	202,	Malaysia - food,	coconut
0,	100,	300,	Australia - capital,	Canberra
0,	200,	300,	Australia -currency,	AUS ollar
0,	300,	300,	Australia - food,	kangaroo
0,	100,	301,	New Zealand - capital,	Wellington
0,	200,	301,	New Zealand - currency,	NZ Dollar
0,	300,	301,	New Zealand - food,	lamb
0,	100,	302,	Japan - capital,	Tokyo
0,	200,	302,	Japan - currency,	yen
0,	300,	302,	Japan - food,	sushi

In this way tests can be created that test you on :

- capital cities of countries in all regions
- foods of europe
- currencies of asia
- anything about countries of the pacific

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 would be configured to includes
all questions in the source file and exclude none.

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

All of the data mentioned above is stored in the test
file as plain text, (use Program editor or Word in text
mode to view a test file if you wish !), ie :

LOC::M:\DAT\NIHONGO.DBF // source data file
English // field 1 label
Japanese // field 2 label
113 // incl. min lesson
113 // incl. max lesson
1   // incl. min group
999 // incl. max group
0   // excl. min lesson
0   // excl. max lesson
31  // excl. min group
32  // excl. max group
comment 1 // !!
comment 2 //
comment 3 //
comment 4 //
comment 5 //

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 using that
source data file.

Data - New Source
-----------------
Allows you to create a new data file to be used
as the source for a reviser test. An option is 
provided to allow the new file to become the
source file for the currently loaded test.

Data - New Source
-----------------
Allows the source data file for the currently loaded
test to be changed to a different one.

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 all test related config (Labels,in/ex/cludes,
comments etc) are saved as part of the test file, while
other config is saved in \opd\reviser.ini, and is loaded
for all tests.

Config - Test comments
----------------------
Each test file can 5 lines of comments stored with 
it to document the test. ie if this test has any
special characters used, abbreviations or needs
any description, use the comments.


Config - Test 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 includes
----------------------
Reviser allows a type of specialisation
in its question selection, in that it can
select questions from subsets within 
subsets of questions.

or "include records matching this criteria"

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. 

These criteria are stored as part of the test file.

Config - Test excludes
----------------------
Allows you to add extra criteria for a test, stopping
records from within a range from being used.

Why ? Imagine you have a set of records, which you wish
to list/print/be tested on, but which contains some
records you wish to exclude.

ie If you have records from lesson 13, grouped into
groups 1,2,3,4 and 5. If you wish to test yourself,
on groups 1,2 and 5, the Test includes criteria won't
allow such specific selection alone ie:

Min lesson : 13
Max lesson : 13
Min group  : 1
Max group  : 5

would force the inclusion of groups 3 and 4.

Setting Test exclusion to :

Min lesson : 0
Max lesson : 0
Min group  : 3
Max group  : 4

would exclude groups 3 and 4.

If you do not wish to exclude any records within a
range, simply set all Test excludes criteria to 0.
In fact if you never set them, they will stay
defaulted to 0s and you need never bother with them.

These criteria are stored as part of the test file.

If you had been using v3.0 or earlier of Reviser,
the old test files will still work, as the Test
excludes criteria will default to 0s and will get
saved  in addition to the old data, without any
intervention on your part.

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.

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

Select (n)one, (m)emory, or (f)ile then
press Enter to mark this record and proceed
to the next question.

Alternatively, use the 'speed keys', by
pressing Shift and the appropriate choice.
ie Shift-m (Uppercase M) will select the memory
marking option and will immediately proceed to
the next question, circumventing the need to
press Enter.

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.

Editing records during a test
-----------------------------
During any test it is possible to edit the
currently displayed record, once the answer
has been displayed. Any changes made are 
reflected immediately, and do not affect
the test, except : if you change the lesson
or group details to be outside of the tests
range the record will be removed from the
current test.

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



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 :-)



