Significantly improve documentation (6bb1d18)

documentation.md

@@ -25,14 +25,29 @@ quotes: A.N. Whitehead on automatic thought processes: ;;Civilization advances b
 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 either 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. Pick a directory to store your deck and images.
-3. Make a blank `SOMETHING.rec` file there.
-4. Edit `~/.config/memoire/config.rec` (see Configuration section).
+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`.
-5. If you want to use vocal review, make sure you have eSpeak installed.
-6. Run `src/main.lua` on the command line.
+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
@@ -63,17 +78,18 @@ 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):
+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`/`-`), and press Enter, to indicate, respectively, that you
+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.


...	...	@@ -25,14 +25,29 @@ quotes: A.N. Whitehead on automatic thought processes: ;;Civilization advances b
25	25	then Memoire will construct four prompts from the card.
26	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	27
	28	+You may be able to include images in cards (of either type) with `IMG[path/to/image]` syntax, where the path is relative to the directory containing your deck file.
	29	+For example, if the note is
	30	+```memoire
	31	+machines: what is this thing? IMG[img/velomobile.jpg] {velomobile}
	32	+```
	33	+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`.
	34	+
	35	+I say "may be able to" sith this feature expects a particular unpublished program I have on my system.
	36	+
28	37	## Setup
	38	+I have only used Memoire on Linux.
	39	+It will probably only work on Linux.
	40	+You can try to run it on a different system, but you'll have to hack the code a bit.
	41	+
29	42	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).
	43	+2. Make sure you have Lua installed.
	44	+3. Pick a directory to store your deck and images.
	45	+4. Make a blank `SOMETHING.rec` file there.
	46	+5. Edit `~/.config/memoire/config.rec` (see Configuration section).
33	47	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.
	48	+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.
	49	+7. If you want to use vocal review, make sure you have eSpeak installed.
	50	+8. Run `src/main.lua` on the command line.
36	51	Most operations you might want to do relating to it are implemented as command-line options in `src/main.lua`.
37	52
38	53	## Adding cards
...	...	@@ -63,17 +78,18 @@ At the start of each line is the number of the card in the deck.
63	78	## Review (in the terminal)
64	79	`src/main.lua r` runs a review session.
65	80
66		-For each prompt due for review (up to the limit you specify at the start):
	81	+For each prompt due for review, up to the limit you specify at the start (this gets much easier than it looks):
67	82	1. Memoire presents the prompt.
68	83	2. You think of the answer (or fail to do so after trying).
69	84	3. You press Enter.
70	85	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
	86	+5. You enter something starting with `a`/`h`/`g`/`e`/`c` (or `0`/`1`/`2`/`3`/`-`) to indicate, respectively, that you
72	87	- failed to recall
73	88	- recalled only with great effort
74	89	- recalled with moderate effort
75	90	- recalled easily
76	91	- see an issue with the note
	92	+6. You add `q` to the end of that input iff you want to quit early, and press Enter.
77	93
78	94	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	95	The prompts you reviewed are scheduled for later review according to your responses and a fancy formula.
80	96