#+TITLE: Gnosis User Manual
#+AUTHOR: Thanos Apollo
#+email: public@thanosapollo.org
#+language: en
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
#+macro: stable-version 0.1.7
#+macro: release-date 2023-02-18
#+macro: development-version 0.1.8-dev
#+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 And Self-Testing
#+texinfo_header: @set MAINTAINERSITE @uref{https://thanosapollo.org,maintainer webpage}
#+texinfo_header: @set MAINTAINER Thanos Apollo
#+texinfo_header: @set MAINTAINEREMAIL @email{public@thanosapollo.org}
#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:public@thanosapollo.org,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=


Advanced/Power users may prefer to use =gnosis-add-note--TYPE=

Example: 

#+begin_src emacs-lisp
  (gnosis-add-note--basic :deck "DECK-NAME"
  			:question "Your Question"
  			:answer "Answer"
  			:hint "hint"
  			:extra "Explanation"
  			:image "Image displayed before user-input" ;; Optional
  			:second-image "Image displayed after user-input" ;; Optional
  			:tags '("tag1" "tag2"))
#+end_src

By default, the value of image and second image is nil. Their value
must a string, the path of an image, from inside ~gnosis-images-dir~.

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.

Every note type has these values in common:

 + ~extra~ string value, extra information/explanation displayed after user-input
 + ~image~ Image displayed /before/ user input
 + ~second-image~ Image displayed /after/ user input

The following sections will cover the important differences you have
to know when creating new notes.

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

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

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

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

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

To use =gnosis-test=, first you have to =(require 'gnosis-test)= & run
=M-x gnosis-test-start=. This will create a new database 'testing'
with random inputs.

To exit the testing environment, rerun =M-x gnosis-test-start= and
then enter =n= (no) at the prompt "Start development env?"

** Adjust for 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."

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

* 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. Initial 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, 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:

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

* 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

You might as well add