memoire

Revise documentation.md
Parent e875469
dkl9

dkl9 commited on 2024-15 10:39:47
Showing 1 changed files, with 48 additions and 19 deletions. 

- fix mistake in "Overview" section
- many little edits for concision and sanity
- explain `cys` cards
- add "Helper scripts" section (cf 9cb4e4c, 4962ab3, e875469)
documentation.md
View file @ 919259f
... ... 
@@ -5,45 +5,67 @@ It is primarily for my own use and may well be too idiosyncratic or mediocre to
5 5 
 ## Overview
6 6 
 Here's how you memorise knowledge with Memoire, roughly the same as with any spaced repetition program:
7 7 
 1. [Set up Memoire.]( #setup )
8 
-1. Learn something.
9 
-2. Distill knowledge into one or more [notes, suitable for cards]( #data-format ).
10 
-3. [Add those cards]( #adding-cards ) to your deck.
11 
-4. [Review]( #review-in-the-terminal ) your deck every day (or a bit more or less often, if needed) as Memoire directs.
12 
-5. [Correct]( #correcting-cards ) notes when you realise they're wrong or unhelpful.
13 
-6. Repeat steps 1-3 whenever appropriate.
14 
-7. Be a genius (well, maybe).
8 
+2. Learn something.
9 
+3. Distill knowledge into one or more [notes, suitable for cards]( #data-format ).
10 
+4. [Add those cards]( #adding-cards ) to your deck.
11 
+5. [Review]( #review-in-the-terminal ) your deck every day (or a bit more or less often, if needed) as Memoire directs.
12 
+6. [Correct]( #correcting-cards ) notes when you realise they're wrong or unhelpful.
13 
+7. Repeat steps 2-4 whenever appropriate.
14 
+8. Be a genius (well, maybe).
15 15
16 16 
 ## Data format
17 17 
 Any time you run Memoire, it will operate on a deck.
18 18 
 A deck is stored as a [Recfile]( https://www.gnu.org/software/recutils/manual/The-Rec-Format.html ).
19 19 
 A deck consists of a list of cards, each card corresponding to a record.
20 20 
 A card consists of a note and some associated fields, and may be expanded to a list of prompts generated from the note.
21 
-For now, there are three types of cards: basic multi-cloze, pairwise cloze, and sequential.
21 
+For now, there are four types of cards: basic multi-cloze, cyclic, pairwise cloze, and sequential.
22 22
23 
-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.
23 
+### Basic multi-cloze (`bmc`)
24 
+Each note contains one or more cloze deletions, delimited with curly brackets.
25 
+There is a prompt for each such deletion, showing the entire note except that deletion.
24 26 
 For example, if the note is
25 27 
 ```memoire
26 28 
 bio organelles: matter enters the {Golgi apparatus} on the {cis face} and exits {in a vesicle} on the {trans face}
27 29 
 ```
28 
-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".
30 
+then Memoire will make four prompts, one omitting "Golgi apparatus", one omitting "cis face", one omitting "in a vesicle", and one omitting "trans face".
29 31 
 Each prompt has the deletion re-inserted as the answer.
30 32
31 
-From a pairwise cloze card, the note is broken into clauses, separated by double-semicolons.
33 
+### Cyclic (`cys`)
34 
+Each note contains two or more clauses, separated by double-semicolons, and ends with a terminal double-semicolon.
35 
+Text before the first double-semicolon is treated as context.
36 
+There is a prompt for each clause, showing the context and that clause alone.
37 
+For example, if the note is
38 
+```memoire
39 
+bio: ;;agar, made of ;;semisolid polysaccharide, found ;;from red algae, used in microbiology as substrate, that's called ;;
40 
+```
41 
+then Memoire will make three prompts.
42 
+One will be "bio: agar, made of", and another will be "bio: semisolid polysaccharide, found".
43 
+Each prompt has the next clause appended as the answer.
44 
+The prompt for the last clause has the first clause as its answer, hence "cyclic".
45 
+
46 
+### Pairwise cloze (`pwc`)
47 
+Each note contains two or more clauses, separated by double-semicolons.
48 
+Text before the first double-semicolon is treated as context.
49 
+Each clause may contain a cloze deletion, delimited by curly brackets.
32 50 
 There is a prompt for each ordered pair of distinct clauses for which the second clause has a cloze deletion.
33 51 
 For example, if the note is
34 52 
 ```memoire
35 53 
 words zh:;; hanzi 面包;; pronounced {miànbāo};; means {bread} (en)
36 54 
 ```
37 
-then Memoire will construct four prompts for the card, two asking for pronunciation (omitting "miànbāo"), two asking for meaning (omitting "bread").
55 
+then Memoire will make four prompts, two asking for pronunciation (omitting "miànbāo"), two asking for meaning (omitting "bread").
38 56
39 
-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.
57 
+### Sequential (`seq`)
58 
+Each note contains two or more clauses, separated by double-semicolons.
59 
+Text before the first double-semicolon is treated like any other clause.
60 
+There is a prompt for each clause, which shows the part of the note before that clause.
40 61 
 For example, if the note is
41 62 
 ```memoire
42 63 
 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.
43 64 
 ```
44 
-then Memoire will construct four prompts from the card.
65 
+then Memoire will make four prompts.
45 66 
 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.
46 67
68 
+### Images
47 69 
 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.
48 70 
 For example, if the note is
49 71 
 ```memoire
... ... 
@@ -53,6 +75,8 @@ and your deck file is at `/home/jsmith/memoire/deck.rec`, then, when reviewing,
53 75
54 76 
 I say "may be able to" sith this feature expects a particular unpublished program I have on my system.
55 77
78 
+Some [scripts]( #helper-scripts ), which have their own dependencies, may help you make images for cards.
79 
+
56 80 
 ## Setup
57 81 
 I have only used Memoire on Linux.
58 82 
 It will probably only work on Linux.
... ... 
@@ -62,7 +86,7 @@ You can try to run it on a different system, but you'll have to hack the code a
62 86 
 2. Make sure you have Lua installed.
63 87 
 3. Pick a directory to store your deck and images.
64 88 
 4. Make a blank `SOMETHING.rec` file there.
65 
-5. Edit `~/.config/memoire/config.rec` (see Configuration section).
89 
+5. Edit `~/.config/memoire/config.rec` (see [Configuration section]( #configuration )).
66 90 
     Make sure to at least put in `DeckFile`, pointing to your `SOMETHING.rec`.
67 91 
 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.
68 92 
 7. If you want to use vocal review, make sure you have eSpeak installed.
... ... 
@@ -75,10 +99,10 @@ The notes must be separated by blank lines.
75 99 
 Each note can have multiple lines.
76 100 
 There must be an extra blank line at the end of the input.
77 101
78 
-This feature auto-detects the type of card (multi-cloze, pairwise cloze, or sequential) from the content of the note.
102 
+This feature auto-detects the [type of card]( #data-format ) from the content of the note.
79 103 
 If the note is formatted plausibly like pairwise cloze, it's saved as pairwise cloze.
80 104 
 If there are braces, it's saved as multi-cloze.
81 
-If there are double-semicolons, it's saved as sequential.
105 
+If there are double-semicolons, it's saved as cyclic (if there is a final double-semicolon) or as sequential (otherwise).
82 106 
 If both are present (and it was not detected as pairwise cloze), the procedure favours multi-cloze.
83 107
84 108 
 ## Correcting cards
... ... 
@@ -101,7 +125,7 @@ At the start of each line is the number of the card in the deck.
101 125 
 `src/main.lua r` runs a review session.
102 126
103 127 
 For each prompt due for review, up to the limit you specify at the start (this gets much easier than it looks):
104 
-1. Memoire presents the prompt.
128 
+1. Memoire shows the prompt.
105 129 
 2. You think of the answer (or fail to do so after trying).
106 130 
 3. You press Enter.
107 131 
 4. Memoire reveals the answer.
... ... 
@@ -113,7 +137,7 @@ For each prompt due for review, up to the limit you specify at the start (this g
113 137 
     - see an issue with the note
114 138 
 6. You add `q` to the end of that input iff you want to quit early, and press Enter.
115 139
116 
-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.
140 
+At the end, you get brief statistics on your results and a list of any prompts you marked as having flawed notes, with their card-numbers.
117 141 
 The prompts you reviewed are scheduled for later review according to your responses and a fancy formula.
118 142
119 143 
 ## Statistics
... ... 
@@ -149,3 +173,8 @@ Most configuration is done with a Recfile at `~/.config/memoire/config.rec`, whi
149 173 
 - `StartingEase`: the ease-value assigned to a new prompt, default 2.5.
150 174 
     Higher ease means reviews will be spaced apart more.
151 175 
     Ease is adjusted by reviews.
176 
+
177 
+## Helper scripts
178 
+Included with Memoire are shell scripts `frames.sh` and `occlude.sh`, the latter of which works differently when invoked from symlink `highlight.sh`.
179 
+They are meant to help make [images]( #images ) for cards.
180 
+The files each contain comments documenting their usage.
152 181