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 Note Taking System.
@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 (GNU-sis) is a customizable spaced repetition system designed to enhance
memory retention through active recall.  It allows users to set
specific review intervals for note decks & tags, creating an optimal
learning environment tailored to each specific topic/subject.

@noindent
This manual is written for Gnosis version 0.4.4, released on 2024-10-06.

@itemize
@item
Manual:
@itemize
@item
@uref{https://elpa.nongnu.org/nongnu/doc/gnosis.html}
@item
@uref{https://thanosapollo.org/projects/gnosis/} (Mirror)
@end itemize
@item
Git repositories:
@itemize
@item
@uref{https://git.thanosapollo.org/gnosis}
@item
@uref{https://codeberg.org/thanosapollo/emacs-gnosis} (Mirror)
@item
@uref{https://git.savannah.gnu.org/cgit/emacs/nongnu.git/?h=elpa/gnosis} (Mirror)
@end itemize
@end itemize

@insertcopying

@end ifnottex

@menu
* Introduction::
* Adding notes::
* Note Types::
* Customization::
* Gnosis Algorithm::
* Editing notes::
* Configuring Note Types::
* Sync between devices::
* Interactions with other software::
* Contributing::

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

Note Types

* Cloze::
* MC-Cloze (Under development)::
* MCQ::
* Basic Type::
* Double::
* y-or-n::

Customization

* Image size::
* Typos | String Comparison::

Gnosis Algorithm

* Anagnosis Event::
* Proto::

Configuring Note Types

* Custom Note Types::
* Development::

Interactions with other software

* emacs-no-littering::

Contributing

* How to create a patch::

@end detailmenu
@end menu

@node Introduction
@chapter Introduction

Gnosis (γνῶσις) is a spaced repetition system that enhances memory
retention through active recall. It employs a Q&A format, where each
note consists of a question, answer, and explanation. Notes are
reviewed at optimally spaced intervals based on the user's success or
failure to recall the answer.  Key benefits arise from writing out
answers when reviewing notes, fostering deeper understanding
and improved memory retention.

Gnosis algorithm is highly adjustable, allowing users to set specific
values not just for note decks but for tags as well.  Gnosis'
adjustability allows users to fine-tune settings not only for entire
note collections but also for specific tagged topics, thereby creating
a personalized learning environment for each topic.  Read more on
@ref{Gnosis Algorithm}

Before continuing reading this manual, it's recommended you try out
@samp{gnosis-demo}.

@node Adding notes
@chapter Adding notes

Creating notes for gnosis can be done interactively with:

@samp{M-x gnosis-add-note}

Or from within @samp{gnosis-dashboard}

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 (Under development)::
* MCQ::
* 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.

@itemize
@item
If a cloze is repeated, such as in phrases with ``acetyl'' &
acetylcholine, include whitespace in the cloze to denote a single
word.
@end itemize

@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 (Under development)
@section MC-Cloze (Under development)

MC-Cloze is disabled by default, to enable it add to your configuration:

@samp{(add-to-list 'gnosis-note-types "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
@section MCQ

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 a gnosis score, which is a list of 3 values,
(gnosis-plus gnosis-minus gnosis-synolon/total).  Gnosis-synolon is
what is used to determine the next interval upon a successful recall,
gnosis-plus is added to gnosis-synolon upon a successful recall as
well, gnosis-minus is subtracted from gnosis-synolon upon failing to
recall a note's answer.

Gnosis has 2 special events, one is @code{anagnosis} @emph{ανάγνωση} and @code{lethe} @emph{λήθη}.

@menu
* Anagnosis Event::
* Proto::
@end menu

@node Anagnosis Event
@section Anagnosis Event

@code{Anagnosis}, which means comprehension & recognition of knowledge, is
triggered when the consecutive successful or failed recalls are equal
or greater to anagnosis value.

When @code{anagnosis} is triggered by consecutive @strong{successful} recalls,
@code{epignosis} value is added to gnosis-plus.  @emph{Epignosis means accuracy of knowledge}.

When @code{anagnosis} is triggered by consecutive @strong{failed} recalls,
@code{agnoia} value is added to gnosis-minus. @emph{Agnoia means lack of knowledge}

You can set specific values for each deck and tag of the variables
mentioned above by adjusting @samp{gnosis-custom-values}.

@node Proto
@section Proto

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

@samp{gnosis-algorithm-interval} is a list of numbers, representing the
first initial intervals for successful reviews.  There is no limit on
the length of the list.

Example:

@lisp
(setq gnosis-algorithm-interval '(0 1 2 30))
@end lisp

Upon each successful note review, the algorithm will increment to the
next interval value: 0 days (0), 1 day later (1), 2 days later
(2), and 30 days later.

Upon failing to review a note without completing it's proto successful reviews,
it's next review date will be on the same date.

@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 Configuring Note Types
@chapter Configuring Note Types

@menu
* Custom Note Types::
* Development::
@end menu

@node Custom Note Types
@section Custom Note Types

Each gnosis note type has an @emph{interactive} function, named
@samp{gnosis-add-note-TYPE} and a ``hidden'' function
named @samp{gnosis-add-note--TYPE}.  You can create your own custom interactive
functions to ignore or hard-code specific values by using already
defined hidden functions that handle all the logic.

For example:

@lisp
(defun gnosis-add-note-custombasic (deck)
  (gnosis-add-note--basic :deck deck
                          :question (gnosis-read-string-from-buffer "Question: " "")
                          :answer (read-string "Answer: ")
                          :hint (gnosis-hint-prompt gnosis-previous-note-hint)
                          :extra ""
                          :images nil
                          :tags (gnosis-prompt-tags--split gnosis-previous-note-tags)))
;; Add custom note type to gnosis-note-types
(add-to-list 'gnosis-note-types "custombasic")
@end lisp

Now @code{custombasic} is available as a note type, for which you won't be prompted to enter
anything for @code{extra} & @code{images}.

@node Development
@section Development

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?''

@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, no-littering is ~/.emacs.d/var/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 Interactions with other software
@chapter Interactions with other software

@menu
* emacs-no-littering::
@end menu

@node emacs-no-littering
@section emacs-no-littering

If you are a user of @uref{https://github.com/emacscollective/no-littering, emacs-no-littering}, you can theme Gnosis to fit
its standards by adding the following snippet to your configuration:

@lisp
(setq gnosis-dir (no-littering-expand-var-file-name "gnosis/"))
@end lisp

This sets @samp{gnosis-dir} to @samp{~/.emacs.d/var/gnosis}, in line with the folders of other packages.

@node Contributing
@chapter Contributing

Thank you for considering contributing back to gnosis.  You can
contribute by submitting a pull request on the codeberg mirror
repository, or directly sending me patch via email.

@menu
* How to create a patch::
@end menu

@node How to create a patch
@section How to create a patch

@emph{Example:}

@example
$ git clone https://git.thanosapollo.com/gnosis.git && cd gnosis
$ emacs something
$ git add something
$ git commit -m "Fix something"
$ git format-patch HEAD^1
0001-Fix-something.patch
@end example

You can sent the patch to ``Thanos Apollo'', the email of which you can
find on the git log.

@bye