path: root/doc/gnosis.texi

\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.2.0, released on 2023-03-08.

@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::
* Adding notes::
* Note Types::
* Customization::
* Gnosis Algorithm::
* Editing notes::
* Sync between devices::
* Extending Gnosis::

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

Note Types

* Cloze::
* MCQ (Multiple Choice Question)::
* Basic Type::
* Double::
* 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 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
@ref{Gnosis Algorithm}

@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}.  For adjusting image size, refer to @ref{Customization}

@node Note Types
@chapter Note Types

@menu
* Cloze::
* MCQ (Multiple Choice Question)::
* Basic Type::
* Double::
* 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.  A fill-in-the-blanks question.  

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

You can remove the @emph{guidance} string by adjusting
@samp{gnosis-cloze-guidance}.

@node MCQ (Multiple Choice Question)
@section 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
@samp{gnosis-mcq-separator}, each option is separated by @samp{gnosis-mcq-option-separator}.

You can remove the @emph{guidance} string by adjusting
@samp{gnosis-mcq-guidance}.

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

@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 300)
@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

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 @samp{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 @samp{gnosis-dashboard}.

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

@node Initial Interval
@section Initial Interval

The default initial interval is defined at
@samp{gnosis-algorithm-interval}, you can define a custom initial interval
for each deck as well.

@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 '(0 1))
@end lisp

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.

@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
Total Easiness factor: Used to calculate the next interval.
@end enumerate


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:

@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

You can set a custom @samp{gnosis-algorithm-ff} for each deck as well.

@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-note-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