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

@noindent
This manual is written for Gnosis version 0.3.1, released on 2024-07-15.

@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::
* MC-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

Before reading this manual, it's recommended you first try out @samp{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
@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::
* MC-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::drug name@} 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 so prefer; e.g @code{@{@{c1::Cyproheptadine::drug name@}@}}

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

@item
You can use the keyword @samp{::} to indicate a hint.
@end itemize

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

@node MC-Cloze
@section MC-Cloze

A MC-Cloze (@emph{Multiple Choice Cloze}) is a fill-in-the-blank note,
but unlike @ref{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 @strong{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 @samp{gnosis-mc-cloze-separator} (default value is ``&&''), and a
note will be generated from each cloze.

Example:
@quotation
The greatest text editor is Emacs&&Vim&&Helix

@end quotation

When customizing @samp{gnosis-mc-cloze=separator} pay attention to not use
values that would mess up with regex functions.

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

Upon failing to review a note without completing 2 successful reviews,
you will have to review it again on the same day.

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