Write documentation.md (aac0e5d) - memoire

documentation.md

...	...	@@ -0,0 +1,113 @@
	1	+Memoire is a [spaced repetition]( https://en.wikipedia.org/wiki/Spaced_repetition )/memorisation/study program, usable entirely in the terminal.
	2	+I made it largely out of frustration with the slow performance of Anki.
	3	+It is primarily for my own use and may well be too idiosyncratic or mediocre to benefit you.
	4	+
	5	+## Data format
	6	+Any time you run Memoire, it will operate on a deck.
	7	+A deck is stored as a [Recfile]( https://www.gnu.org/software/recutils/manual/The-Rec-Format.html ).
	8	+A deck consists of a list of cards, each card corresponding to a record.
	9	+A card consists of a note and some associated fields, and may be expanded to a list of prompts generated from the note.
	10	+For now, there are two types of cards: basic multi-cloze and sequential.
	11	+
	12	+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.
	13	+For example, if the note is
	14	+```memoire
	15	+bio organelles: matter enters the {Golgi apparatus} on the {cis face} and exits {in a vesicle} on the {trans face}
	16	+```
	17	+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".
	18	+Each prompt has the deletion re-inserted as the answer.
	19	+
	20	+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.
	21	+For example, if the note is
	22	+```memoire
	23	+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.
	24	+```
	25	+then Memoire will construct four prompts from the card.
	26	+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.
	27	+
	28	+## Setup
	29	+1. Download the source code.
	30	+2. Pick a directory to store your deck and images.
	31	+3. Make a blank `SOMETHING.rec` file there.
	32	+4. Edit `~/.config/memoire/config.rec` (see Configuration section).
	33	+ Make sure to at least put in `DeckFile`, pointing to your `SOMETHING.rec`.
	34	+5. If you want to use vocal review, make sure you have eSpeak installed.
	35	+6. Run `src/main.lua` on the command line.
	36	+ Most operations you might want to do relating to it are implemented as command-line options in `src/main.lua`.
	37	+
	38	+## Adding cards
	39	+`src/main.lua a` reads standard input for notes from which to generate cards, and saves them to the deck.
	40	+The notes must be separated by blank lines.
	41	+Each note can have multiple lines.
	42	+There must be an extra blank line at the end of the input.
	43	+
	44	+This feature can only generate basic multi-cloze cards.
	45	+For now, to make a sequential card, you must input the note to the add-cards feature and manually edit the Recfile to set the card's `CardType` field to `seq`.
	46	+
	47	+## Correcting cards
	48	+`src/main.lua c N` (where `N` is an integer) opens the note for card N from the deck in a text editor.
	49	+Edits performed in the editor (once you save and exit) will be applied to the note saved in the deck.
	50	+
	51	+You do not need to manually count out N!
	52	+Use the query feature.
	53	+
	54	+## Leech search
	55	+`src/main.lua l` outputs a list of all (non-suspended) prompts which are judged to be "leeches" by their unusual difficulty.
	56	+At the start of each line is a pair of numbers `M:N`.
	57	+M is the number of the card, and N is the number of the leech-prompt in the card.
	58	+
	59	+## Querying the deck
	60	+`src/main.lua q A` (where `A` is a string) outputs a list of all cards with A in the note.
	61	+At the start of each line is the number of the card in the deck.
	62	+
	63	+## Review (in the terminal)
	64	+`src/main.lua r` runs a review session.
	65	+
	66	+For each prompt due for review (up to the limit you specify at the start):
	67	+1. Memoire presents the prompt.
	68	+2. You think of the answer (or fail to do so after trying).
	69	+3. You press Enter.
	70	+4. Memoire reveals the answer.
	71	+5. You enter something starting with `a`/`h`/`g`/`e`/`c` (or `0`/`1`/`2`/`3`/`-`), and press Enter, to indicate, respectively, that you
	72	+ - failed to recall
	73	+ - recalled only with great effort
	74	+ - recalled with moderate effort
	75	+ - recalled easily
	76	+ - see an issue with the note
	77	+
	78	+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.
	79	+The prompts you reviewed are scheduled for later review according to your responses and a fancy formula.
	80	+
	81	+## Statistics
	82	+`src/main.lua s` presents statistics on your deck, including several histograms.
	83	+- ease: a number (usually 2 to 3) representing how easy a prompt is to remember
	84	+- log2-delay: the base-2 logarithm of the delay scheduled between when you reviewed a prompt and when you should review it again
	85	+- retention: the proportion of reviews of a prompt at which you (indicate that you) recalled it successfully
	86	+- review counts: the number of times you reviewed each prompt
	87	+- prompt-count: the number of prompts generated from each card
	88	+
	89	+## Toggling prompts
	90	+`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.
	91	+
	92	+## Vocal review
	93	+`src/main.lua v` runs a review session.
	94	+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.
	95	+
	96	+## Configuration
	97	+Most configuration is done with a Recfile at `~/.config/memoire/config.rec`, which supports the following options:
	98	+- `AllowedRandomVariation`: the maximum magnitude, as a proportion of the calculated interval, by which the actual interval may be randomly adjusted, default 0.1.
	99	+ 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.
	100	+- `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.
	101	+- `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`)
	102	+- `EspeakFlags`: a string of command-line flags to pass to eSpeak during vocal reviews, default empty.
	103	+- `HardRatio`: the ratio by which to scale intervals for prompts reviewed with a "hard" rating, default 1.2.
	104	+- `PriorityBias`: a constant of mysterious units by which to bias the urgency of a prompt from a note containing corresponding `PriorityText`.
	105	+ Positive values make the prompt more urgent, and negative values, less urgent.
	106	+ 0.1 is a reasonable magnitude for this value.
	107	+- `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.
	108	+ You can have multiple `PriorityText` fields to prioritise multiple groups of cards.
	109	+ Each one must have a corresponding `PriorityBias`.
	110	+- `ShowProgress`: `true` or `false` to determine whether to show a progress indicator in review sessions, default false.
	111	+- `StartingEase`: the ease-value assigned to a new prompt, default 2.5.
	112	+ Higher ease means reviews will be spaced apart more.
	113	+ Ease is adjusted by reviews.
0	114