
                        SUPER-MEMO TOOLKIT

  A wide range of professional and semi-professional tools have been
  developed to assist users of SuperMemo 6 and SuperMemo 7 in development
  of professional SuperMemo databases. If not specified otherwise, all
  programs work with databases of both SuperMemo 6 and SuperMemo 7.
  The Toolkit programs are:
    RESCUE.EXE - used to recover from database damage resulting from
      viruses, hardware failures, user errors, etc. (in SuperMemo 6,
      RESCUE.EXE is named RECOV6.EXE; in SuperMemo 7.3 and later, the
      recovery procedures are built in the program)
    RESET.EXE - used to convert SuperMemo databases to intact form. In the
      intact form, databases look the same as directly after their
      development, before any learning process started.
      For example, Memorized=0, Burden=0, Workload=0, etc.
      (in SuperMemo 6, RESET.EXE is named RESET6.EXE)
    TRANSFER.EXE - used to transfer items between two SuperMemo databases.
      The transferred items retain their learning parameters, including
      the date of the next repetition. They can also be reset to
      intact form.
      The program may be used to merge or split databases.
    TO_TEXT.EXE - used to convert SuperMemo databases to a text form, and
      to compute ordinal numbers that can be used in database sorting.
      The ordinal numbers are established on the basis of the learning
      process, and are supposed to reflect the difficulty of particular
      items. By means of the SM_SORT, a database may be sorted with respect
      to ordinal numbers, and consequently, provide easy items at the
      beginning, and difficult items at the end of database files.
      (example databases sorted with respect to ordinals established by
      TO_TEXT: Advanced English, English Vocabulary, Human Biology).
    TO_SORT.EXE - used to convert SuperMemo database text files (extension
      TXT) to sortable files (extension STB).
    SM_SORT.EXE - used to sort STB files with respect to ordinal numbers
      established by (1) TO_TEXT or (2) manually by the developer of the
      database.
      Sorted files have the extension SRT.
    TO_SM.EXE - used to convert sortable STB files, or sorted SRT files
      back to the SuperMemo format (extension ITM)
    CROSS.EXE - used to compute a statistical cross-section through a number
      of databases. Such parameters are computed as the total number of items,
      total number of outstanding items, average burden, average knowledge
      retention, and many more.
    UP_2_5.EXE - used to convert SuperMemo 2 database format to the format
      acceptable by SuperMemo 5
    UP_5_6.EXE - used to convert SuperMemo 5 database format to the format
      acceptable by SuperMemo 6
    REPSTR.EXE - used to replace fonts or substrings in a SuperMemo
      database with another set of fonts or substrings
    FONTDES.EXE - used to define fonts used by databases in SuperMemo 6
      (only releases 6.6 and later)
    SWAP.EXE - used to swap questions with answers in SuperMemo databases
      (e.g. to convert active-use vocabulary database to a passive-use
      vocabulary database)
    CLEAN.EXE - used to reset optimization matrices used by a given
      database. The forgetting index, retention, and average grade are
      also reset.
    GATHER.EXE - used to collect optimization matrices from several
      databases, and to place the cumulative data in a selected
      destination database
    MULTI.EXE - used to generate multiple bilingual vocabulary databases
      from multilingual text source files
    BRANCH.EXE - used to copy BMP and WAV files used in the Standard
      file access mode, to the directory tree used by CD-ROM and CD-ROM
      Alias modes

                  HOW TO USE THE TOOLKIT PROGRAMS

    RESCUE.EXE -
      1. run RESCUE.EXE
      2. in the file selection window, choose the database to recover, and
         press Enter
      3. inspect the <database name>.REC file to analyse the results of
         recovery
      4. optionally, the command-line syntax can be used:
            RESCUE <database name>
    Note that as of SuperMemo 7.3, the recovery procedures have been
    integrated with the program. Instead of running RESCUE.EXE, choose
    File:Recover.

    RESET.EXE -
      1. run RESET.EXE
      2. in the file selection window, choose the database to convert to
         the unused form, and press Enter
      3. (optionally, use Miscells|Garbage in SuperMemo to compact the
         <database name>.ITM file)
      4. optionally, the command-line syntax can be used:
            RESET <database name>

    TRANSFER.EXE -
      0. prepare a range file in which subsequent lines will define the
         range of items to be transferred. For example:
            1-22
            25-60
            2000-2999
         The range file should have the extension RNG.
      1. run TRANSFER.EXE
      2. in the file selection window, choose the source database from
         which the items will be transferred (if you change the extension
         to TXT, you can also use text files generated by TRANSFER.EXE as
         the source)
      3. in the file selection window, choose the range file, or press
         ESC if your want to transfer all the items from the source
         database
      4. in the file selection window, choose the destination database
         to which the items are to be sent
      5. optionally, the command-line syntax can be used:
            TRANSFER <options>
          where available options are:
            S=<name of the source database>
            D=<name of the destination database>
            R=<name of the range file, without extension>
            RESET - reset the transferred items
            TXT - generate a text file with the transferred items
            ALL - transfer all the items from the source database
            NO_WAV - do not transfer wave files
            NO_BMP - do not transfer bitmap files
            <no1>-<no2> - single range of items to be transferred
               (the variable MAX may be used in place of <no2>)
        For example:
          - merging databases GEOG1 with GEOG2:
              TRANSFER S=GEOG2 D=GEOG1 ALL
          - fast merging text databases ENGLISH1 with ENGLISH2:
              TRANSFER S=ENGLISH2 D=ENGLISH1 ALL NO_WAV NO_BMP
          - moving items 2000-2999 from a colleague's database
            ALEX to the database MY_DB:
              TRANSFER S=ALEX D=MY_DB 2000-2999 RESET
          - splitting LARGE:
              TRANSFER S=LARGE D=SMALL1 1-5000
              TRANSFER S=LARGE D=SMALL2 5001-MAX
              (Note, empty databases SMALL1 and SMALL2 must exist
              beforehand)
          - editing the parameters of a used database or changing
            the order of items in a used database:
              1. TRANSFER S=OLD D=DUMMY TXT
              2. process the text file OLD.TXT
              3. run TRANSFER again and use OLD.TXT as the source
                 database

    TO_TEXT.EXE -
      0. prepare a filter file used by TO_TEXT.EXE (see later)
      1. run TO_TEXT.EXE
      2. in the file selection window, choose the database to convert to
         the text format, and press Enter (DO NOT RESET THE DATABASE
         WITH RESET.EXE BEFORE CONVERSION, IF YOU WANT THE TEXT FILE TO
         BE SORTED LATER ON)
      3. in the file selection window, choose the filter file (extension
         FLT)
      4. optionally, run TO_TEXT.EXE with the command line syntax:
            TO_TEXT N=<database name> F=<filter filename> <options>
         where options are:
           LABEL - label particular items with the name of the source
                   database
           ORDATA - display data used to compute ordinal numbers
           NO_WAV - speed up processing by ignoring wave files
           NO_BMP - speed up processing by ignoring bitmap files
           CUT_BRACK - cut comments in square brackets
           CUT_ANG - cut comments in angle brackets
           CUT_BRACE - cut comments in braces
      5. inspect the <database name>.TXT file to analyse the results of
         conversion, and the ordinal numbers
           An exemplary item generated by TO_TEXT is presented below:

              d: REP=5 RES=0 EF=2.660 UF=2.797 INT=621 LAST=05.06.93
              i: LEN=33 INT=29 EF=7 LAPS=0 REPS=37 ORD=20
              c:
              o: 20
              k:
              q: bus: accumulated wealth used in production of
              q: further wealth
              a: capital

           In the example above the following lines are present:
             d: item data used by TRANSFER.EXE
             i: item ranking for difficulty (see below)
             c: category
             o: overall ordinal number (used in sorting)
             k: keyword
             q: question
             a: answer
           The above item is ranked on a point scale from 0 to 100 in
           the following categories (see Line i:):
             LEN - length of the answer, 33% difficulty
             INT - length of the current interval, 29% difficulty
             EF - E-factor, 7% difficulty
             LAPS - Memory lapses, 0% difficulty
             REPS - No of repetitions, 37% difficulty,
             ORD - Overall difficulty used in sorting the database: 20
           Note that the filter file may request modifying the ordinal
           number ORD which will then differ from the o: ordinal.

      6. Note the following:
          - if the COMMENT option has been specified, comments placed in
            angle brackets will not be transferred to the TXT file
            as in the example below:
              ITM file
                  Question
                    What is the annual US defence budget? <1990>
                  Answer
                    about 300 billion US dollars
              TXT file
                  q: What is the annual US defence budget?
                  a: about 300 billion US dollars
         - the following characters are disallowed in the source file:
             #219   - full-block character (used as a separator in
                      ITM files)
             #1     - smiling-face character (used as a separator in
                      STB and SRT files)
      7. Filter files used by TO_TEXT.EXE are text files with the
         extension FLT. They contain the following sections:
           [ORDINALS] - defines substrings that affect the ordinal
             numbers of items. For example
                 form: 20
             indicates that the substring 'form:' will increase the ordinal
             number according to the formula ord=ord+(100-ord)*20%
           [INCLUDE] - defines substrings that qualify items for
             inclusion in particular output files. For example:
                 bus: business
             indicates that the items containing 'bus:' should be
             placed in the file BUSINESS.TXT
           [EXCLUDE] - defines substrings that disqualify items
           [DELIMITERS] - defines delimiters used to place comments
             and ordinal numbers in items. For example:
               <  > cut
             indicates that comments placed in angle brackets should be
             cut while
               {  } ordinal
             indicates that ordinals placed in braces should supplant
             ordinals computed from item parameters
           [CUT] - defines strings that should be cut from items
           [REPLACE]  - defines strings that should be replaced with
             other strings. For example:
               bus. bus:
             indicates that 'bus.' should be replaced with 'bus:'
           [OPTIONS] - defines options such as SLIM, FULL (opposite to
             slim), NO-WAV, NO-BMP, SOUND <no> (defines a shifting ordinal
             for items associated with sound), INTACT <no> (defines a
             shifting ordinal for intact items), POS-ORD (using overriding
             position ordinals), ORDATA (see the command syntax), LLO
             (last line ordinals), RESET (resets processed items),
             REVERSE (reverses the direction in which string replacement
             takes place), etc.
             For example:
               LLO 5 1
             indicates that all items contain ordinal numbers placed
             in the last line of the question. The easiest items have
             ordinals 5, and the most difficult items have ordinals 1.
               POS-ORD 80
             indicates that position of the item in the database will
             be weighted against the standardly computed ordinals
             along the 80:20 proportion.
               SOUND -25
             indicates that ordinals of items associated with sound should
             be reduced by 25%.
               INTACT 40
             indicates that ordinals of intact items should be increased
             by 40%.

    TO_SORT.EXE -
      1. run TO_SORT.EXE
      2. in the file selection window, choose the <database name>.TXT file
         to convert to the sortable STB format, and press Enter
      3. optionally, run TO_SORT.EXE with the command line syntax:
            TO_SORT N=<database name>
      4. inspect the <database name>.STB file to analyse the results of
         conversion.
           An exemplary item generated by TO_SORT is presented below:

              79 bus: money value of real assets => share-capital #0#0

           where 79 corresponds to the overall difficulty used in sorting
           the database by means of SM_SORT.EXE
      Remember! In the TXT file, items must be separated by at least one
         empty line.

    SM_SORT.EXE -
      1. run SM_SORT.EXE
      2. in the file selection window, choose the <database name>.STB file
         to convert to the sortable SRT format, and press Enter
      3. optionally, run SM_SORT.EXE with the command line syntax:
            SM_SORT N=<database name>
      4. inspect the <database name>.SRT file to analyse the results of
         conversion. The format of SRT files is the same as that of STB
         files with the exception that SRT files are sorted for the overall
         difficulty; lower difficulty coming first
      (see COMPILE.BAT which illustrates the compilation stages used by
       SuperMemo World to compile the Advanced English database from 14
       SuperMemo source databases)

    TO_SM.EXE -
      1. run TO_SM.EXE
      2. in the file selection window, choose the <database name>.SRT or
         <database name>.STB file to convert it to the SuperMemo ITM format,
         and press Enter
      3. optionally, run TO_SM.EXE with the command line syntax:
            TO_SM [N=<SRT filename>] [/L] [S=<size>] [NO_BMP] [NO_WAV]
         where:
           /L switch is used to request cutting labels generated by TO_TEXT
              with option LABEL
           S=<size> is used to determined the maximum size of the database
              (in case the database is greater than <size> then it will be
              split to portions filenamed <name>00, <name>01, etc.
           NO_BMP speeds up processing by ignoring bitmap files
           NO_WAV speeds up processing by ignoring wave files
      4. inspect the database by means of SuperMemo
      (see COMPILE.BAT which illustrates the compilation stages used by
       SuperMemo World to compile the Advanced English database from 14
       SuperMemo source databases)

    CROSS.EXE -
      1. run CROSS.EXE
      2. type name of the report file (the extension will always be REP)
      3. in the file selection window, choose the name of the CRS file
         with the list of databases subject to analysis, or press ESC if
         you have not created such a file.
         In the CRS text file, database names must be placed in separate
         lines without filename extensions, e.g.
            BIOL1
            BIOL2
            BIOL3, etc.
      4. if you have not created the CRS file, in the file selection window,
         one by one, choose the names of databases which are subject to
         analysis (no more than 20 databases can be scanned)
      5. optionally, run CROSS.EXE with the command line syntax:
            CROSS <CRS filename>
         where <CRS filename>.CRS is a text file which lists the names of
         databases subject to analysis (see Point 4)
      6. an exemplary result of the analysis is shown below:

     Name  a_hb  b_hb  c_hb  d_hb  e_hb  f_hb  g_hb  h_hb  Aver Total
     Date 08.92 08.92 08.92 08.92 08.92 08.92 08.92 08.92
      Day  1696  1452   958   856   745   593   563   471   949     -
    Total   992   996  1001  1001   999  1001   999   439   965  7428
Memorized   992   996  1001  1001   999  1001   999   439   965  7428
 Outstand     9     7    11     4     2    11    10     9   7.8    63
   Burden  4.87  3.28  4.50  7.89  8.53 11.29 13.18  8.70  7.72 62.25
     Time  9.21  8.47  8.20  8.34  7.90  5.60  6.44  6.43  7.66     -
 Workload  0.75  0.46  0.61  1.10  1.12  1.05  1.42  0.93  0.93  7.45
 Interval 619.4 592.9 614.0 523.2 359.0 311.1 271.1 149.1 450.9     -
   Factor 2.067 2.122 2.143 2.145 2.144 2.146 2.225 2.335 2.153     -
      Rep  6.09  6.20  4.79  4.85  4.70  5.06  6.00  4.79  5.35     -
  Day/Rep 278.6 234.0 199.9 176.6 158.6 117.3  93.9  98.4 174.9     -
   Lapses  1.12  0.90  0.74  0.71  0.70  0.73  0.59  0.32  0.76     -
FI assumed   15    12     8     7     5     4     3     3     7     -
       FI 21.18 19.09 18.58 15.79 13.09 11.05  8.73  6.76 14.84     -
   FI_sup  1893  1917  1938  2477  3522  5212  7163  2322  3381 26444
  Quality 2.782 3.040 3.063 3.064 3.063 2.975 3.232 3.745 3.074     -
     Last 05.98 10.96 10.96 11.95 10.94 05.94 06.94 02.94
     1.3s   148   130   118   106   105   100    83    21   107   811
    Dif 1  0.67  0.79  0.83  1.48  1.47  0.09  0.20  0.15  0.75     -
    Dif 2  0.14  0.20  0.10  0.22  0.15  0.11  0.10 -0.03  0.14     -
    Dif 3  0.12  0.11  0.06  0.10  0.09  0.07  0.06  0.11  0.09     -
OF[1.3,1] 11.26 10.39  4.93  2.18  2.02  1.92  1.21  1.53  4.64     -
OF[1.3,2]  1.87  2.00  1.52  1.21  1.21  1.44  1.20  3.32  1.60     -
OF[1.3,3]  1.57  1.41  1.51  1.27  1.20  1.20  1.20  1.20  1.33     -
OF[2.5,1] 19.28 19.87 14.92 19.91 19.67  2.95  3.59  3.35 13.66     -
OF[2.5,2]  3.59  4.42  2.71  3.89  3.00  2.77  2.36  2.93  3.23     -
OF[2.5,3]  2.99  2.78  2.21  2.45  2.25  2.00  1.92  2.47  2.38     -

        The meaning of particular rows is as follows:

     Name - name of the database
     Date - date on which last repetitions were made (month.year)
      Day - day of the learning process
    Total - total number of items in the database
Memorized - total number of memorized items in the database
 Outstand - number of outstanding items in the database
   Burden - burden parameter (sum of inverse intervals)
     Time - repetition time per item in seconds
 Workload - repetition time in minutes per session
 Interval - average interval
   Factor - average E-factor
      Rep - average number of repetitions per item
  Day/Rep - average number of days between repetitions per item
   Lapses - average number of memory lapses per item
FI assumed- the requested forgetting index (Lapses parameter)
       FI - the measured forgetting index
   FI_sup - number of repetition cases used to measure the FI value above
  Quality - average response quality (Grade)
     Last - date of the most remote repetition (month.year)
     1.3s - number of bad items (E-factor = 1.3)
    Dif 1 - average difference between optimal factors for two E-factor
            columns in the OF matrix for the first repetition
    Dif 2 - ditto, for the second repetition
    Dif 3 - ditto, for the third repetition
OF[1.3,1]
OF[1.3,2]       Optimal factor values OF[EF,Rep] where
OF[1.3,3]          - EF - E-factor
OF[2.5,1]          - Rep - number of the repetition
OF[2.5,2]
OF[2.5,3]
        The Aver and Total columns list the average and the sum of
        values in the database columns.

    GATHER.EXE -
      1. run GATHER.EXE
      2. in the file selection window, one by one, choose the names of
         databases which are to provide optimization data collected in
         the output database
      3. press Esc when finished
      4. in the file selection window, choose the name of the database
         which is to store the data collected in Step 2. Note, that this
         database should be newly created or reset; otherwise, its
         optimization data will be added to the data collected in Step 2
         (unless this is your intention)
      5. inspect the results in the output database by using options such
         as Retention factors, Cases, and, in SuperMemo 7, Graph

    MULTI.EXE -
      0. prepare a text source file containing multilingual vocabulary
         entries. Each entry should be preceded by a language marker,
         for example E: for English, F: for French, etc. Each group of
         entries should be separated from other groups by a blank line.
         The text could look as follows:

            A: devil
            G: Teufel
            E: diablo

            A: cat
            G: Katze
            E: kato

      1. run MUTLI.EXE
      2. in the file selection window choose the name name of the source
         text file containing multilingual vocabulary entries.
         which are to provide optimization data collected in
         the output database
      3. convert the newly created SRT files to databases by means of
         TO_SM.EXE (MULTI.EXE will generate n*(n-1) databases, where n
         is the number of languages used in the source file). You can
         use the batch file automatically generated by MULTI.EXE

    UP_2_5.EXE (only for SuperMemo 2.x) -
       Run UP_2_5.EXE and follow the instructions on the screen.
       Have the database number of the upgraded copy handy.
       The new database will be created without affecting *.DB files
       of SuperMemo 2.

    UP_5_6.EXE (only for SuperMemo 5.7 and 5.8) -
       Run UP_2_5.EXE and follow the instructions on the screen.
       The database number will automatically be determined.
       Old database files of SM5 will be upgraded and no new database
       files will be created. If you wish to keep the files in both
       the SM5 and SM6 formats then back up the SM5 database beforehand.

    REPSTR.EXE -
      1. prepare a conversion file. The file should have the extension
         CNV, and should contain, in successive lines, pairs of fonts
         or substrings to convert. Spaces should separate the fonts or
         substrings in each of the pairs. Spaces in replaced substring
         should be denoted as #32 (to avoid confusion with the
         separator). For example:
           the club
           club #5
           .#32. ._.
         In the example above, all 'the' and 'club' substrings will be
         replaced by a club symbol, and dots separated by a space will be
         replaced by ._.
	 Note, that the sequence of pairs in the CNV file may influence
         the way the conversion is done. For example, if the first two
         lines in the example above were swapped, 'club' strings would be
         replaced with a club symbol, and 'the' strings would be replaced
         with the string 'club'.
      2. run REPSTR.EXE
      3. in the file selection window, choose the conversion file
         prepared in Step 1, and press Enter
      4. in the file selection window, choose the database to convert,
         and press Enter
      5. inspect the results of conversion by means of SuperMemo
      6. optionally, use the command-line syntax:
            REPSTR [N=<database name>] [C=<conversion file name>]
         (Do not provide filename extensions in the command tail)
      To delete a substring from the database, set the second element
      of the pair to an empty word. If necessary, provide special
      characters with their codes preceded by #.
      Note, items that are longer than 48 characters per line will be
      truncated.
      (You can also use REPSTR to convert text files and binary files.
      Provide parameter TXT or BIN in such cases. Output files will be
      stored with the extension NEW. The binary conversion will use only
      the first character of conversion strings)

    FONTDES.EXE (only for SuperMemo 6 releases 6.6 and later) -
      1. Copy and rename any FNT font file to be used with
         your database (the name should be <database name>.FNT)
      2. Run FONTDES.EXE
      3. Press F3 for Load, and choose the FNT file to be
         modified (the same as created in Step 1)
      4. Press P for Pick, and specify the code of the character you
         want to modify (e.g. 65 for 'A', 97 for 'a', etc.)
      5. Use arrow keys and Space to change the character bitmap
         according to your design
      6. If you want to modify more characters, goto 4
      7. Press ESC to quit FONTDES.EXE
      8. Copy the FNT file to the directory with other files of the
         database in question
      The format of the FNT file is as follows:
        - 8 bytes of the font header
            $AA $55 $08 $00 $10 $00 $10 $00
        - 4096 bytes of the font definition

    SWAP.EXE -
      1. run SWAP.EXE
      2. in the file selection window, choose the database whose items are
         to be swapped

    CLEAN.EXE -
      1. run CLEAN.EXE
      2. in the file selection window, choose the database whose
         learning process is to be reset

    BRANCH.EXE -
      1. run BRANCH.EXE using the followig syntax:
             BRANCH <source database> <destination directory>
      2. note that the destination directory must have room for all
         WAV and BMP files taken from the source database, and it
         must contain the file LINK.DIR, which may be empty
      3. inspect the sound and bitmap referencing in the source
         database by setting Miscellaneous:Options:AudioVis files
         mode to CD-ROM, and by providing the same path as the
         destination directory (only SuperMemo 7.4 or later)
      The CD-ROM directory structure can be transferred to a CD-R
      (compact disk recordable) or to a magnetoptical device. This
      way, a substantial saving in hard disk space taken by audiovisual
      databases can be made.

=======================================================================

       SUPER-MEMO WORLD
       P.O. Box 1
       Poznan 48
       POLAND
       Tel: (48) 61 764066, 764073, 203157
       Fax: (48) 61 764073, 793435
