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.1.8, released on 2023-02-21.

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

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

Installation

* Using straight.el: Using straightel. 
* Installing manually from source::

Note Types

* Cloze::
* Basic Type::
* Double::
* MCQ (Multiple Choice Question)::
* 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 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.

@node Installation
@chapter Installation

Gnosis is available via MELPA
@itemize
@item
@uref{https://melpa.org/#/gnosis}
@end itemize

@menu
* Using straight.el: Using straightel. 
* Installing manually from source::
@end menu

@node Using straightel
@section Using straight.el

If you have not installed straight.el, follow the instructions here:

@uref{https://github.com/radian-software/straight.el}

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

@lisp
(straight-use-package 
 '(gnosis :type git
        :host nil
        :repo "https://git.thanosapollo.org/gnosis"))
@end lisp

@node Installing manually from source
@section Installing manually from source

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

@itemize
@item
Clone gnosis repository

@example
$ git clone https://git.thanosapollo.org/gnosis ~/.emacs.d/site-lisp/gnosis
@end example

@item
Add this to your emacs configuration

@lisp
(add-to-list 'load-path "~/.emacs.d/site-lisp/gnosis")
(load-file "~/.emacs.d/site-lisp/gnosis/gnosis.el")
@end lisp
@end itemize

@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}. See more customization for @ref{Image size, , Image Size}

@node Note Types
@chapter Note Types

@menu
* Cloze::
* Basic Type::
* Double::
* MCQ (Multiple Choice Question)::
* 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. 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 @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

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

@node MCQ (Multiple Choice Question)
@section 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

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

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

@node Initial Interval
@section Initial Interval

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

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.

@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
Initial total easiness factor: Used to calculate the next interval.

@item
How this is used:
@end enumerate

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:

@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

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