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