summaryrefslogtreecommitdiff
path: root/doc/gnosis.org
blob: dc2e1f51bd6c617d8164ab6509992adcbc539823 (about) (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
#+TITLE: Gnosis User Manual
#+AUTHOR: Thanos Apollo
#+email: [email protected]
#+language: en
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
#+macro: stable-version 0.3.1
#+macro: release-date 2024-07-15
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
#+texinfo_filename: gnosis.info
#+texinfo_dir_category: Emacs misc features
#+texinfo_dir_title: Gnosis (γνῶσις): (gnosis) 
#+texinfo_dir_desc: Spaced Repetition System For Note Taking & Self-Testing
#+texinfo_header: @set MAINTAINERSITE @uref{https://thanosapollo.org,maintainer webpage}
#+texinfo_header: @set MAINTAINER Thanos Apollo
#+texinfo_header: @set MAINTAINEREMAIL @email{[email protected]}
#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:[email protected],contact the maintainer}



Gnosis (γνῶσις), pronounced "noh-sis", /meaning knowledge in Greek/,
is a spaced repetition system implementation for note taking and self
testing.  Notes are organized in a Question/Answer/Explanation format
and reviewed at spaced intervals, determined by the success or failure
to recall the answer.

The goal of Gnosis is to enhance memory retention through active
recall.  To achieve optimal results, users review Gnosis notes by
writing out the answers.

Above all, Gnosis aspires to be a versatile instrument of learning.

#+texinfo: @noindent
This manual is written for Gnosis version {{{stable-version}}}, released on {{{release-date}}}.

+ Official manual: <https://thanosapollo.org/user-manual/gnosis>
+ Git repositories:
  + <https://git.thanosapollo.org/gnosis>

#+texinfo: @insertcopying

* Introduction

Before reading this manual, it's recommended you first try out =gnosis-demo=

Gnosis, is a spaced repetition system for note taking & self
testing, where notes are taken in a Question/Answer/Explanation
format & reviewed in spaced intervals, determined by the success or
failure to recall a given answer.

Gnosis implements a highly customizable algorithm, inspired by SM-2.
Gnosis algorithm does not use user's subjective rating of a note to
determine the next review interval, but instead uses the user's
success or failure in recalling the answer of a note.  Read more on
[[Gnosis Algorithm]]

* Adding notes
Creating notes for gnosis can be done interactively with:

    =M-x gnosis-add-note=

When it comes to adding images, you can select images that are inside
=gnosis-images-dir=.  For adjusting image size, refer to [[#Customization][Customization]]

* Note Types
** Cloze
:PROPERTIES:
:CUSTOM_ID: Cloze
:END:
A cloze note type is a format where you create sentences or paragraphs
with "missing" words.  A fill-in-the-blanks question.  

You can create a cloze note type using =M-x gnosis-add-note= and
selecting ~Cloze~, the question should be formatted like this:

#+BEGIN_QUOTE
{c1:Cyproheptadine::drug name} is a(n) {c2:5-HT2} receptor antagonist used to treat {c2:serotonin syndrome}
#+END_QUOTE

You can also format clozes like Anki if you so prefer; e.g ~{{c1::Cyproheptadine::drug name}}~

+ For each cX-tag there will be created a cloze type note, the above
  example creates 2 cloze type notes.
  
+ Each cX tag can have multiple clozes, but each cloze must be a
  *UNIQUE* word (or a unique combination of words) in given note.

+ You can use the keyword =::= to indicate a hint.

You can remove the /guidance/ string by adjusting
=gnosis-cloze-guidance=.

** MC-Cloze
A MC-Cloze (/Multiple Choice Cloze/) is a fill-in-the-blank note,
but unlike [[#Cloze][cloze note type]] the user is prompted to select an option
instead of typing an answer.

You can create multiple notes from one input, but each note can only
have *one* cloze. The first option will always be the right answer
(will be randomized in the database), separated by the rest of the
answer by =gnosis-mc-cloze-separator= (default value is "&&"), and a
note will be generated from each cloze.

Example:
#+BEGIN_QUOTE
    The greatest text editor is Emacs&&Vim&&Helix
#+END_QUOTE

When customizing =gnosis-mc-cloze=separator= pay attention to not use
values that would mess up with regex functions.
** MCQ (Multiple Choice Question)

A MCQ note type, as the name suggests, is a multiple choice question.

The stem field (question) is separated by the options (choices) via
=gnosis-mcq-separator=, each option is separated by =gnosis-mcq-option-separator=.

You can remove the /guidance/ string by adjusting
=gnosis-mcq-guidance=.

** Basic Type

Basic note type is a simple question/answer note, where the user first
sees a "main" part, which is usually a question, and he is prompted to
input the answer. 

** Double
Double note type, is essentially a note that generates 2 basic notes.
The second one reverses question/answer.

Ideal for vocabulary acquisition notes.

** y-or-n
y-or-n (yes or no) note type, user is presented with a question and
prompted to enter character "y" or "n".

When using the hidden function =gnosis-add-note--y-or-n=, note that the
ANSWER must be either 121 (~y~) or 110 (~n~), as those correspond to the
character values used to represent them.

* Customization
:PROPERTIES:
:CUSTOM_ID: Customization
:END:
** Image size
:PROPERTIES:
:CUSTOM_ID: image-size
:END:
Adjust image size using =gnosis-image-height= & =gnosis-image-width=

Example:
#+begin_src emacs-lisp
(setf gnosis-image-height 300
      gnosis-image-width 300)
#+end_src
** Typos | String Comparison
You can adjust =gnosis-string-difference=, this is a threshold value
for string comparison that determines the maximum acceptable
Levenshtein distance between two strings, which identifies their
similarity

Let's illustrate with an example:
#+begin_src emacs-lisp
(setf gnosis-string-difference 1)
#+end_src

In this scenario, we set =gnosis-string-difference= to 1. This implies
that two strings will be recognized as similar if they exhibit a
difference of at most one character edit.

To demonstrate, 'example' and 'examples' will be recognized as
similar, considering that the latter involves just one additional
character."

* Gnosis Algorithm

Each gnosis note has an ef (easiness factor), which is a list of 3
values.  The last value is the total ef for a note, which will be
used to determine the next interval upon a successful answer recall,
the second value is the ef-decrease value, this value will be
subtracted from the the total ef upon failure to recall the answer of
a note, the first value is the ef increase, will be added to the
total ef upon a successful recall.

Each gnosis deck has =gnosis-algorithm-ef-threshold=, it's an
integer value that refers to the consecutive success or failures to
recall an answer.  Upon reaching the threshold, gnosis-algorithm-ef-decrease
or gnosis-algorithm-ef-increase will be applied to the ef-increase or
ef-decrease of note.

You can customize deck specific algorithm values using =gnosis-dashboard=.

** Initial Interval

The default initial interval is defined at
=gnosis-algorithm-interval=, you can define a custom initial interval
for each deck as well.

=gnosis-algorithm-interval= is a list of 2
numbers, representing the first two initial intervals for successful
reviews.

Example:

#+begin_src emacs-lisp
  (setq gnosis-algorithm-interval '(0 1))
#+end_src

Using the above example, after first successfully reviewing a note,
you will see it again in the next review session, if you successfully
review said note again, the next review will be tomorrow.

Upon failing to review a note without completing 2 successful reviews,
you will have to review it again on the same day.

** Easiness Factor

The =gnosis-algorithm-ef= is a list that consists of three items:

1. Easiness factor increase value: Added to the easiness factor upon a
   successful review.
   
2. Easiness factor decrease value: Subtracted from the total easiness
   factor upon a failed review.
   
3. Total Easiness factor: Used to calculate the next interval.


How this is used:
  
Multiplies the last interval by the easiness factor after a successful
review.

For example, upon a successful review, if the last review was 6 days
ago with an easiness factor of 2.0, the next interval would be
calculated as 6 * 2.0, and the next total easiness factor would be
updated by adding the increase value 2.0 + <increase-value>.

Configuration example:

#+begin_src emacs-lisp
  (setq gnosis-algorithm-ef '(0.30 0.25 1.3))
#+end_src

** Forgetting Factor

=gnosis-algorithm-ff= is a floating number below 1.

Used to determine the next interval after an unsuccessful review.

Multiplied with the last interval to calculate the next interval. For
example, if =gnosis-algorithm-ff= is set to 0.5 and the last interval
was 6 days, the next interval will be 6 * 0.5 = 3 days.


Example configuration:

#+begin_src emacs-lisp
  (setq gnosis-algorithm-ff 0.5)
#+end_src

You can set a custom =gnosis-algorithm-ff= for each deck as well.
* Editing notes
+ Currently there are 2 ways for editing notes:

    + You can edit a note after review by pressing ~e~
    + Open =gnosis-dashboard= with =M-x gnosis-dashboard=, find the note you want to edit and press ~e~
* Sync between devices

Gnosis uses git to maintain data integrity and facilitate
synchronization across devices.

You will need to configure your remote manually.

Example:

#+begin_src bash
 cd ~/.emacs.d/gnosis # default location for gnosis
 git init # After completing your first review session, a git repo should have been initialized automatically.
 git remote add origin <remote_url>
 git push --set-upstream origin master
#+end_src


You can interactively use =gnosis-vc-push= & =gnosis-vc-pull=. As the
name suggests, they rely on =vc= to work properly.

Depending on your setup, =vc= might require an external package for
the ssh passphrase dialog, such as ~x11-ssh-askpass~.


To automatically push changes after a review session, add this to your configuration:
#+begin_src emacs-lisp
(setf gnosis-vc-auto-push t)
(gnosis-vc-pull) ;; Run vc-pull for gnosis on startup
#+end_src

* Extending Gnosis
To make development and customization easier, gnosis comes with
=gnosis-test= module, that should be used to create a custom database for
testing.

To exit the testing environment, rerun =M-x gnosis-test-start= and
then enter =n= (no) at the prompt "Start development env?"

** Creating Custom Note Types

Creating custom note types for gnosis is a fairly simple thing to do

+ First add your NEW-TYPE to =gnosis-note-types=

    #+begin_src emacs-lisp
    (add-to-list 'gnosis-note-types "new-note-type")
  #+end_src

+ Create 2 functions; =gnosis-add-note-TYPE= & =gnosis-add-note--TYPE=

Each note type has a =gnosis-add-note-TYPE= that is used
interactively & a "hidden function" =gnosis-add-note--TYPE= that handles
all the logic.

Refer to =gnosis-add-note-basic= & =gnosis-add-note--basic= for a simple
example of how this is done.

+ Create =gnosis-review-TYPE=

This function should handle the review process, displaying it's
contents and updating the database depending on the result of the
review (fail/pass). Refer to =gnosis-review-basic= for an example of how
this should be done.

+ Optionally, you might want to create your own custom =gnosis-display= functions