summaryrefslogtreecommitdiff
path: root/doc/gnosis.texi
blob: 745f7ff17044db62083d1bf921472381d28fe726 (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
\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename gnosis.info
@settitle Gnosis User Manual
@documentencoding UTF-8
@documentlanguage en
@set MAINTAINERSITE @uref{https://thanosapollo.org,maintainer webpage}
@set MAINTAINER Thanos Apollo
@set MAINTAINEREMAIL @email{[email protected]}
@set MAINTAINERCONTACT @uref{mailto:[email protected],contact the maintainer}
@c %**end of header

@dircategory Emacs misc features
@direntry
* Gnosis (γνῶσις): (gnosis). Spaced Repetition System For Note Taking & Self-Testing.
@end direntry

@finalout
@titlepage
@title Gnosis User Manual
@author Thanos Apollo (@email{public@@thanosapollo.org})
@end titlepage

@ifnottex
@node Top
@top Gnosis User Manual

Gnosis (γνῶσις), pronounced ``noh-sis'', @emph{meaning knowledge in Greek}, is
a spaced repetition system implementation for note taking and self
testing.

@noindent
This manual is written for Gnosis version 0.1.8, released on 2023-02-21.

@itemize
@item
Official manual: @uref{https://thanosapollo.org/user-manual/gnosis}
@item
Git repositories:
@itemize
@item
@uref{https://git.thanosapollo.org/gnosis}
@end itemize
@end itemize

@insertcopying
@end ifnottex

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

@detailmenu
--- The Detailed Node Listing ---

Installation

* Using straight.el: Using straightel. 
* Installing manually from source::

Note Types

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

Customization

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

Gnosis Algorithm

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

Extending Gnosis

* Creating Custom Note Types::

@end detailmenu
@end menu

@node Introduction
@chapter Introduction

Gnosis is a spaced repetition note taking and self testing system,
where notes are taken in a Question/Answer/Explanation-like format &
reviewed in spaced intervals.

Gnosis can help you better understand and retain the material by
encouraging active engagement. It also provides a clear structure for
your notes & review sessions, making it easier to study.

@node Installation
@chapter Installation

Gnosis is available via MELPA
@itemize
@item
@uref{https://melpa.org/#/gnosis}
@end itemize

@menu
* Using straight.el: Using straightel. 
* Installing manually from source::
@end menu

@node Using straightel
@section Using straight.el

If you have not installed straight.el, follow the instructions here:

@uref{https://github.com/radian-software/straight.el}

Once you have installed straight.el, you can install gnosis using the
following emacs lisp snippet:

@lisp
(straight-use-package 
 '(gnosis :type git
        :host nil
        :repo "https://git.thanosapollo.org/gnosis"))
@end lisp

@node Installing manually from source
@section Installing manually from source

Gnosis depends on the @code{compat} & @code{emacsql} libraries which are available
from MELPA@. Install them using @code{M-x package-install RET <package> RET}
or you may also install them manually from their repository.

@itemize
@item
Clone gnosis repository

@example
$ git clone https://git.thanosapollo.org/gnosis ~/.emacs.d/site-lisp/gnosis
@end example

@item
Add this to your emacs configuration

@lisp
(add-to-list 'load-path "~/.emacs.d/site-lisp/gnosis")
(load-file "~/.emacs.d/site-lisp/gnosis/gnosis.el")
@end lisp
@end itemize

@node Adding notes
@chapter Adding notes

Creating notes for gnosis can be done interactively with:
  @samp{M-x gnosis-add-note}

When it comes to adding images, you can select images that are inside
@samp{gnosis-images-dir}. See more customization for @ref{Image size, , Image Size}

@node Note Types
@chapter Note Types

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

@node Cloze
@section Cloze

A cloze note type is a format where you create sentences or paragraphs
with ``missing'' words. Almost all note types can be written as a cloze
type in a way. Ideal type for memorizing definitions.

To get the most out of gnosis, you have to become familiar with cloze type notes.

You can create a cloze note type using @samp{M-x gnosis-add-note} and
selecting @code{Cloze}, the question should be formatted like this:

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

@end quotation

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

@itemize
@item
For each `cX`-tag there will be created a cloze type note, the above
example creates 2 cloze type notes.

@item
Each `cX` tag can have multiple clozes, but each cloze must be a
@strong{UNIQUE} word (or a unique combination of words) in given note.
@end itemize

@node Basic Type
@section 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.

@node Double
@section Double

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

Ideal for vocabulary acquisition, creating vocabulary/translation
notes for a foreign language.

@node MCQ (Multiple Choice Question)
@section MCQ (Multiple Choice Question)

MCQ note type, consists of a ``stem'' part that is displayed, and
``options'' for the user to select the right one.

Answer must be the index NUMBER of the correct answer from OPTIONS@.

Ideal for self testing & simulating exams

@node y-or-n
@section 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 @samp{gnosis-add-note--y-or-n}, note that the
ANSWER must be either 121 (@code{y}) or 110 (@code{n}), as those correspond to the
character values used to represent them.

@node Customization
@chapter Customization

@menu
* Image size::
* Typos | String Comparison::
@end menu

@node Image size
@section Image size

Adjust image size using @samp{gnosis-image-height} & @samp{gnosis-image-width}

Example:
@lisp
(setf gnosis-image-height 300
      gnosis-image-width 500)
@end lisp

@node Typos | String Comparison
@section Typos | String Comparison

You can adjust @samp{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:
@lisp
(setf gnosis-string-difference 1)
@end lisp

In this scenario, we set @samp{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.``

@node Gnosis Algorithm
@chapter Gnosis Algorithm

@menu
* Initial Interval::
* Easiness Factor::
* Forgetting Factor::
@end menu

@node Initial Interval
@section Initial Interval

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

Example:

@lisp
(setq gnosis-algorithm-interval '(1 3))
@end lisp

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

@node Easiness Factor
@section Easiness Factor

The @samp{gnosis-algorithm-ef} is a list that consists of three items:

@enumerate
@item
Easiness factor increase value: Added to the easiness factor upon a
successful review.

@item
Easiness factor decrease value: Subtracted from the total easiness
factor upon a failed review.

@item
Initial total easiness factor: Used to calculate the next interval.

@item
How this is used:
@end enumerate

Multiplies the last interval by the easiness factor after a successful
review.

For example, 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
total easiness factor would be updated by adding the increase factor.

Configuration example:

@lisp
(setq gnosis-algorithm-ef '(0.30 0.25 1.3))
@end lisp

@node Forgetting Factor
@section Forgetting Factor

@samp{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 @samp{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:

@lisp
(setq gnosis-algorithm-ff 0.5)
@end lisp

@node Editing notes
@chapter Editing notes

@itemize
@item
Currently there are 2 ways for editing notes:

@itemize
@item
You can edit a note after review by pressing @code{e}
@item
Open @samp{gnosis-dashboard} with @samp{M-x gnosis-dashboard}, find the note you want to edit and press @code{e}
@end itemize
@end itemize

@node Sync between devices
@chapter Sync between devices

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

You will need to configure your remote manually.

Example:

@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 <remote_name> <remote_url>
git push --set-upstream origin master
@end example


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

Depending on your setup, @samp{vc} might require an external package for
the ssh passphrase dialog, such as @code{x11-ssh-askpass}.


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

@node Extending Gnosis
@chapter Extending Gnosis

To make development and customization easier, gnosis comes with
@samp{gnosis-test} module, that should be used to create a custom database for
testing.

To exit the testing environment, rerun @samp{M-x gnosis-test-start} and
then enter @samp{n} (no) at the prompt ``Start development env?''

@menu
* Creating Custom Note Types::
@end menu

@node Creating Custom Note Types
@section Creating Custom Note Types

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

@itemize
@item
First add your NEW-TYPE to @samp{gnosis-note-types}

@lisp
(add-to-list 'gnosis-note-types 'new-type)
@end lisp

@item
Create 2 functions; @samp{gnosis-add-note-TYPE} & @samp{gnosis-add-note--TYPE}
@end itemize

Each note type has a @samp{gnosis-add-note-TYPE} that is used
interactively & a ``hidden function'' @samp{gnosis-add-note--TYPE} that handles
all the logic.

Refer to @samp{gnosis-add-note-basic} & @samp{gnosis-add-note--basic} for a simple
example of how this is done.

@itemize
@item
Create @samp{gnosis-review-TYPE}
@end itemize

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 @samp{gnosis-review-basic} for an example of how
this should be done.

@itemize
@item
Optionally, you might want to create your own custom @samp{gnosis-display} functions
@end itemize

@bye