summaryrefslogtreecommitdiff
path: root/doc/gnosis.info
blob: f9296f3c315fc56724a41e8a92a82d04f72d44bb (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
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
This is gnosis.info, produced by .texi2any-real version 7.1 from
gnosis.texi.

INFO-DIR-SECTION Emacs misc features
START-INFO-DIR-ENTRY
* Gnosis (γνῶσις): (gnosis). Spaced Repetition System For Note Taking & Self-Testing.
END-INFO-DIR-ENTRY


File: gnosis.info,  Node: Top,  Next: Introduction,  Up: (dir)

Gnosis User Manual
******************

Gnosis (γνῶσις), pronounced "noh-sis", _meaning knowledge in Greek_, is
a spaced repetition system implementation for note taking and self
testing.  The objective of gnosis is to maximize memory retention by
implementing reviewing of information at increasing intervals.

   The intervals grow longer as you become more familiar with the
information, which reinforces long-term retention and reduces the risk
of forgetting

This manual is written for Gnosis version 0.3.0, released on 2024-06-28.

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

* Menu:

* Introduction::
* Adding notes::
* Note Types::
* Customization::
* Gnosis Algorithm::
* Editing notes::
* Sync between devices::
* Extending Gnosis::

-- The Detailed Node Listing --

Note Types

* Cloze::
* MC-Cloze::
* MCQ (Multiple Choice Question)::
* Basic Type::
* Double::
* y-or-n::

Customization

* Image size::
* Typos | String Comparison::

Gnosis Algorithm

* Initial Interval::
* Easiness Factor::
* Forgetting Factor::

Extending Gnosis

* Creating Custom Note Types::



File: gnosis.info,  Node: Introduction,  Next: Adding notes,  Prev: Top,  Up: Top

1 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 *note Gnosis
Algorithm::


File: gnosis.info,  Node: Adding notes,  Next: Note Types,  Prev: Introduction,  Up: Top

2 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 *note
Customization::


File: gnosis.info,  Node: Note Types,  Next: Customization,  Prev: Adding notes,  Up: Top

3 Note Types
************

* Menu:

* Cloze::
* MC-Cloze::
* MCQ (Multiple Choice Question)::
* Basic Type::
* Double::
* y-or-n::


File: gnosis.info,  Node: Cloze,  Next: MC-Cloze,  Up: Note Types

3.1 Cloze
=========

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:

     {c1:Cyproheptadine} is a(n) {c2:5-HT2} receptor antagonist used to
     treat {c2:serotonin syndrome}

   You can also format clozes like Anki if you prefer; e.g
‘{{c1::Cyproheptadine}}’

   • 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 remove the _guidance_ string by adjusting
‘gnosis-cloze-guidance’.


File: gnosis.info,  Node: MC-Cloze,  Next: MCQ (Multiple Choice Question),  Prev: Cloze,  Up: Note Types

3.2 MC-Cloze
============

A MC-Cloze (_Multiple Choice Cloze_) is a fill-in-the-blank note, but
unlike *note cloze note type: Cloze. 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:
     The greatest text editor is Emacs&&Vim&&Helix

   When customizing ‘gnosis-mc-cloze=separator’ pay attention to not use
values that would mess up with regex functions.


File: gnosis.info,  Node: MCQ (Multiple Choice Question),  Next: Basic Type,  Prev: MC-Cloze,  Up: Note Types

3.3 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’.


File: gnosis.info,  Node: Basic Type,  Next: Double,  Prev: MCQ (Multiple Choice Question),  Up: Note Types

3.4 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.


File: gnosis.info,  Node: Double,  Next: y-or-n,  Prev: Basic Type,  Up: Note Types

3.5 Double
==========

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

   Ideal for vocabulary acquisition notes.


File: gnosis.info,  Node: y-or-n,  Prev: Double,  Up: Note Types

3.6 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.


File: gnosis.info,  Node: Customization,  Next: Gnosis Algorithm,  Prev: Note Types,  Up: Top

4 Customization
***************

* Menu:

* Image size::
* Typos | String Comparison::


File: gnosis.info,  Node: Image size,  Next: Typos | String Comparison,  Up: Customization

4.1 Image size
==============

Adjust image size using ‘gnosis-image-height’ & ‘gnosis-image-width’

   Example:
     (setf gnosis-image-height 300
           gnosis-image-width 300)


File: gnosis.info,  Node: Typos | String Comparison,  Prev: Image size,  Up: Customization

4.2 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:
     (setf gnosis-string-difference 1)

   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."


File: gnosis.info,  Node: Gnosis Algorithm,  Next: Editing notes,  Prev: Customization,  Up: Top

5 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’.

* Menu:

* Initial Interval::
* Easiness Factor::
* Forgetting Factor::


File: gnosis.info,  Node: Initial Interval,  Next: Easiness Factor,  Up: Gnosis Algorithm

5.1 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:

     (setq gnosis-algorithm-interval '(0 1))

   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.


File: gnosis.info,  Node: Easiness Factor,  Next: Forgetting Factor,  Prev: Initial Interval,  Up: Gnosis Algorithm

5.2 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:

     (setq gnosis-algorithm-ef '(0.30 0.25 1.3))


File: gnosis.info,  Node: Forgetting Factor,  Prev: Easiness Factor,  Up: Gnosis Algorithm

5.3 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:

     (setq gnosis-algorithm-ff 0.5)

   You can set a custom ‘gnosis-algorithm-ff’ for each deck as well.


File: gnosis.info,  Node: Editing notes,  Next: Sync between devices,  Prev: Gnosis Algorithm,  Up: Top

6 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’


File: gnosis.info,  Node: Sync between devices,  Next: Extending Gnosis,  Prev: Editing notes,  Up: Top

7 Sync between devices
**********************

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

   You will need to configure your remote manually.

   Example:

     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

   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:
     (setf gnosis-vc-auto-push t)
     (gnosis-vc-pull) ;; Run vc-pull for gnosis on startup


File: gnosis.info,  Node: Extending Gnosis,  Prev: Sync between devices,  Up: Top

8 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?"

* Menu:

* Creating Custom Note Types::


File: gnosis.info,  Node: Creating Custom Note Types,  Up: Extending Gnosis

8.1 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’

          (add-to-list 'gnosis-note-types "new-note-type")

   • 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



Tag Table:
Node: Top250
Node: Introduction1503
Node: Adding notes2230
Node: Note Types2599
Node: Cloze2824
Node: MC-Cloze3720
Node: MCQ (Multiple Choice Question)4544
Node: Basic Type5043
Node: Double5346
Node: y-or-n5612
Node: Customization6014
Node: Image size6199
Node: Typos | String Comparison6485
Node: Gnosis Algorithm7260
Node: Initial Interval8296
Node: Easiness Factor9086
Node: Forgetting Factor10034
Node: Editing notes10642
Node: Sync between devices11034
Node: Extending Gnosis12055
Node: Creating Custom Note Types12510

End Tag Table


Local Variables:
coding: utf-8
End: