path: root/doc/gnosis.org

#+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.2.0
#+macro: release-date 2023-03-08
#+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.

#+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
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]]

* Note Types
** 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:

#+BEGIN_QUOTE
{c1:Cyproheptadine} 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 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=.

** 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
** Image size
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.

** 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 <remote_name> <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