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.1.9
#+macro: release-date 2023-02-22
#+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 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.

* Installation

Gnosis is available via MELPA
+ <https://melpa.org/#/gnosis>
  
** Using straight.el
If you have not installed straight.el, follow the instructions here:

   <https://github.com/radian-software/straight.el>

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

#+begin_src emacs-lisp
  (straight-use-package 
   '(gnosis :type git
  	  :host nil
  	  :repo "https://git.thanosapollo.org/gnosis"))
#+end_src

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

+ Clone gnosis repository
  
  #+begin_src shell
    $ git clone https://git.thanosapollo.org/gnosis ~/.emacs.d/site-lisp/gnosis
  #+end_src

+ Add this to your emacs configuration
  
  #+begin_src emacs-lisp
    (add-to-list 'load-path "~/.emacs.d/site-lisp/gnosis")
    (load-file "~/.emacs.d/site-lisp/gnosis/gnosis.el")
  #+end_src

* 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 [[Image size][Image Size]]

* Note Types
** 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 =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.

** MCQ (Multiple Choice Question)

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

First you will be prompted to input the question =stem= field.

Afterwards you will be prompted to enter the choices, each =-=
indicates a choice, the choice inside ={}= will be marked as the
correct one.

Example of options:
#+BEGIN_QUOTE
  - Option 1
  
  - Option 2
  
  - {Correct choice}
#+END_QUOTE


** 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, creating vocabulary/translation
notes for a foreign language.

** 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 500)
#+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
** Initial Interval

=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 '(1 3))
#+end_src

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.

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

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