documentation.md (be34a7d) - memoire

documentation.md

Memoire is a [spaced repetition]( https://en.wikipedia.org/wiki/Spaced_repetition )/memorisation/study program, usable entirely in the terminal.
I made it largely out of frustration with the slow performance of Anki.
It is primarily for my own use and may well be too idiosyncratic or mediocre to benefit you.

## Overview
Here's how you memorise knowledge with Memoire, roughly the same as with any spaced repetition program:
1. [Set up Memoire.]( #setup )
1. Learn something.
2. Distill knowledge into one or more [notes, suitable for cards]( #data-format ).
3. [Add those cards]( #adding-cards ) to your deck.
4. [Review]( #review-in-the-terminal ) your deck every day (or a bit more or less often, if needed) as Memoire directs.
5. [Correct]( #correcting-cards ) notes when you realise they're wrong or unhelpful.
6. Repeat steps 1-3 whenever appropriate.
7. Be a genius (well, maybe).

## Data format
Any time you run Memoire, it will operate on a deck.
A deck is stored as a [Recfile]( https://www.gnu.org/software/recutils/manual/The-Rec-Format.html ).
A deck consists of a list of cards, each card corresponding to a record.
A card consists of a note and some associated fields, and may be expanded to a list of prompts generated from the note.
For now, there are three types of cards: basic multi-cloze, pairwise cloze, and sequential.

From a basic multi-cloze card, there is a prompt for each cloze deletion (indicated with curly brackets around the deletion), which shows the entire note except that deletion.
For example, if the note is
```memoire
bio organelles: matter enters the {Golgi apparatus} on the {cis face} and exits {in a vesicle} on the {trans face}
```
then Memoire will construct four prompts from the card, one omitting "Golgi apparatus", one omitting "cis face", one omitting "in a vesicle", and one omitting "trans face".
Each prompt has the deletion re-inserted as the answer.

From a pairwise cloze card, the note is broken into clauses, separated by double-semicolons.
There is a prompt for each ordered pair of distinct clauses for which the second clause has a cloze deletion.
For example, if the note is
```memoire
words zh:;; hanzi 面包;; pronounced {miànbāo};; means {bread} (en)
```
then Memoire will construct four prompts for the card, two asking for pronunciation (omitting "miànbāo"), two asking for meaning (omitting "bread").

From a sequential card, there is a prompt for each clause (indicated with a double-semicolon separator), which shows the part of the note before that clause.
For example, if the note is
```memoire
quotes: A.N. Whitehead on automatic thought processes: ;;Civilization advances by extending ;;the number of important operations ;;which we can perform ;;without thinking about them.
```
then Memoire will construct four prompts from the card.
One of those will show "quotes: A.N. Whitehead on automatic thought processes: Civilization advances by extending ", and append "the number of important operations " as the answer.

You may be able to include images in cards (of any type) with `IMG[path/to/image]` syntax, where the path is relative to the directory containing your deck file.
For example, if the note is
```memoire
machines: what is this thing? IMG[img/velomobile.jpg] {velomobile}
```
and your deck file is at `/home/jsmith/memoire/deck.rec`, then, when reviewing, Memoire will display the image at `/home/jsmith/memoire/img/velomobile.jpg`.

I say "may be able to" sith this feature expects a particular unpublished program I have on my system.

## Setup
I have only used Memoire on Linux.
It will probably only work on Linux.
You can try to run it on a different system, but you'll have to hack the code a bit.

1. Download the source code.
2. Make sure you have Lua installed.
3. Pick a directory to store your deck and images.
4. Make a blank `SOMETHING.rec` file there.
5. Edit `~/.config/memoire/config.rec` (see Configuration section).
    Make sure to at least put in `DeckFile`, pointing to your `SOMETHING.rec`.
6. If you want to use images, make sure you have at `/usr/local/bin/iv` a image viewer symlink/wrapper script, which accepts an image path on the command line and a `-t title` option to set its window title.
7. If you want to use vocal review, make sure you have eSpeak installed.
8. Run `src/main.lua` on the command line.
    Most operations you might want to do relating to it are implemented as command-line options in `src/main.lua`.

## Adding cards
`src/main.lua a` reads standard input for notes from which to generate cards, and saves them to the deck.
The notes must be separated by blank lines.
Each note can have multiple lines.
There must be an extra blank line at the end of the input.

This feature auto-detects the type of card (multi-cloze, pairwise cloze, or sequential) from the content of the note.
If the note is formatted plausibly like pairwise cloze, it's saved as pairwise cloze.
If there are braces, it's saved as multi-cloze.
If there are double-semicolons, it's saved as sequential.
If both are present (and it was not detected as pairwise cloze), the procedure favours multi-cloze.

## Correcting cards
`src/main.lua c N` (where `N` is an integer) opens the note for card N from the deck in a text editor.
Edits performed in the editor (once you save and exit) will be applied to the note saved in the deck.

You do not need to manually count out N!
Use the query feature.

## Leech search
`src/main.lua l` outputs a list of all (non-suspended) prompts which are judged to be "leeches" by their unusual difficulty.
At the start of each line is a pair of numbers `M:N`.
M is the number of the card, and N is the number of the leech-prompt in the card.

## Querying the deck
`src/main.lua q A` (where `A` is a string) outputs a list of all cards with A in the note.
At the start of each line is the number of the card in the deck.

## Review (in the terminal)
`src/main.lua r` runs a review session.

For each prompt due for review, up to the limit you specify at the start (this gets much easier than it looks):
1. Memoire presents the prompt.
2. You think of the answer (or fail to do so after trying).
3. You press Enter.
4. Memoire reveals the answer.
5. You enter something starting with `a`/`h`/`g`/`e`/`c` (or `0`/`1`/`2`/`3`/`-`) to indicate, respectively, that you
    - failed to recall
    - recalled only with great effort
    - recalled with moderate effort
    - recalled easily
    - see an issue with the note
6. You add `q` to the end of that input iff you want to quit early, and press Enter.

At the end, you get brief statistics on your results and a list of any prompts you marked as having erroneous notes, with their card-numbers.
The prompts you reviewed are scheduled for later review according to your responses and a fancy formula.

## Statistics
`src/main.lua s` presents statistics on your deck, including several histograms.
- ease: a number (usually 2 to 3) representing how easy a prompt is to remember
- log2-delay: the base-2 logarithm of the delay scheduled between when you reviewed a prompt and when you should review it again
- retention: the proportion of reviews of a prompt at which you (indicate that you) recalled it successfully
- review counts: the number of times you reviewed each prompt
- prompt-count: the number of prompts generated from each card

## Toggling prompts
`src/main.lua t M:N` (where `M` and `N` are integers) toggles prompt N of card M from active to suspended (not to be reviewed) or back.

## Vocal review
`src/main.lua v` runs a review session.
This functions mostly the same as `src/main.lua r` (review in the terminal), except that the interface's output is conveyed thru eSpeak text-to-speech, and it is probably much more buggy.

## Configuration
Most configuration is done with a Recfile at `~/.config/memoire/config.rec`, which supports the following options:
- `AllowedRandomVariation`: the maximum magnitude, as a proportion of the calculated interval, by which the actual interval may be randomly adjusted, default 0.1.
    For example, with ARV = 0.1 and a calculated interval of 12 days, the interval actually used may be anywhere from 10.8 days to 13.2 days, selected randomly.
- `BoldContext`: set to any value or absent to determine whether context indicators (the part of a note before the first colon) should be shown in bold.
- `DeckFile`: a path to your deck file, relative to the home directory (e.g. if the deck is in `/home/jsmith/memoire/deck.rec`, write `DeckFile: memoire/deck.rec`)
- `EspeakFlags`: a string of command-line flags to pass to eSpeak during vocal reviews, default empty.
- `HardRatio`: the ratio by which to scale intervals for prompts reviewed with a "hard" rating, default 1.2.
- `PriorityBias`: a constant of mysterious units by which to bias the urgency of a prompt from a note containing corresponding `PriorityText`.
    Positive values make the prompt more urgent, and negative values, less urgent.
    0.1 is a reasonable magnitude for this value.
- `PriorityText`: a pattern of text such that, if a note contains that text, any prompts generated from that note will be regarded as more or less urgent to review than would otherwise be calculated.
    You can have multiple `PriorityText` fields to prioritise multiple groups of cards.
    Each one must have a corresponding `PriorityBias`.
- `ShowProgress`: `true` or `false` to determine whether to show a progress indicator in review sessions, default false.
- `StartingEase`: the ease-value assigned to a new prompt, default 2.5.
    Higher ease means reviews will be spaced apart more.
    Ease is adjusted by reviews.

memoire

Add "Overview" section to documentation.md