path: root/doc/gnosis.info

This is gnosis.info, produced by makeinfo version 7.1 from gnosis.texi.

INFO-DIR-SECTION Emacs misc features
START-INFO-DIR-ENTRY
* Gnosis (γνῶσις): (gnosis). Spaced Repetition System For Note Taking & Self-Testing.
END-INFO-DIR-ENTRY


File: gnosis.info,  Node: Top,  Next: Introduction,  Up: (dir)

Gnosis User Manual
******************

Gnosis (γνῶσις), pronounced "noh-sis", _meaning knowledge in Greek_, is
a spaced repetition system implementation for note taking and self
testing.

This manual is written for Gnosis version 0.2.0, released on 2023-03-08.

   • Official manual: <https://thanosapollo.org/user-manual/gnosis>
   • Git repositories:
        • <https://git.thanosapollo.org/gnosis>

* Menu:

* Introduction::
* Adding notes::
* Note Types::
* Customization::
* Gnosis Algorithm::
* Editing notes::
* Sync between devices::
* Extending Gnosis::

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



File: gnosis.info,  Node: Introduction,  Next: Adding notes,  Prev: Top,  Up: Top

1 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 *note Gnosis
Algorithm::


File: gnosis.info,  Node: Adding notes,  Next: Note Types,  Prev: Introduction,  Up: Top

2 Adding notes
**************

Creating notes for gnosis can be done interactively with:

   ‘M-x gnosis-add-note’

   When it comes to adding images, you can select images that are inside
‘gnosis-images-dir’.  For adjusting image size, refer to *note
Customization::


File: gnosis.info,  Node: Note Types,  Next: Customization,  Prev: Adding notes,  Up: Top

3 Note Types
************

* Menu:

* Cloze::
* MCQ (Multiple Choice Question)::
* Basic Type::
* Double::
* y-or-n::


File: gnosis.info,  Node: Cloze,  Next: MCQ (Multiple Choice Question),  Up: Note Types

3.1 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 ‘M-x gnosis-add-note’ and
selecting ‘Cloze’, the question should be formatted like this:

     {c1:Cyproheptadine} is a(n) {c2:5-HT2} receptor antagonist used to
     treat {c2:serotonin syndrome}

   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.

   You can remove the _guidance_ string by adjusting
‘gnosis-cloze-guidance’.


File: gnosis.info,  Node: MCQ (Multiple Choice Question),  Next: Basic Type,  Prev: Cloze,  Up: Note Types

3.2 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
‘gnosis-mcq-separator’, each option is separated by
‘gnosis-mcq-option-separator’.

   You can remove the _guidance_ string by adjusting
‘gnosis-mcq-guidance’.


File: gnosis.info,  Node: Basic Type,  Next: Double,  Prev: MCQ (Multiple Choice Question),  Up: Note Types

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


File: gnosis.info,  Node: Double,  Next: y-or-n,  Prev: Basic Type,  Up: Note Types

3.4 Double
==========

Double note type, is essentially a note that generates 2 basic notes.
The second one reverses question/answer.

   Ideal for vocabulary acquisition notes.


File: gnosis.info,  Node: y-or-n,  Prev: Double,  Up: Note Types

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


File: gnosis.info,  Node: Customization,  Next: Gnosis Algorithm,  Prev: Note Types,  Up: Top

4 Customization
***************

* Menu:

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


File: gnosis.info,  Node: Image size,  Next: Typos | String Comparison,  Up: Customization

4.1 Image size
==============

Adjust image size using ‘gnosis-image-height’ & ‘gnosis-image-width’

   Example:
     (setf gnosis-image-height 300
           gnosis-image-width 300)


File: gnosis.info,  Node: Typos | String Comparison,  Prev: Image size,  Up: Customization

4.2 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:
     (setf gnosis-string-difference 1)

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


File: gnosis.info,  Node: Gnosis Algorithm,  Next: Editing notes,  Prev: Customization,  Up: Top

5 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 ‘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
‘gnosis-dashboard’.

* Menu:

* Initial Interval::
* Easiness Factor::
* Forgetting Factor::


File: gnosis.info,  Node: Initial Interval,  Next: Easiness Factor,  Up: Gnosis Algorithm

5.1 Initial Interval
====================

The default initial interval is defined at ‘gnosis-algorithm-interval’,
you can define a custom initial interval for each deck as well.

   ‘gnosis-algorithm-interval’ is a list of 2 numbers, representing the
first two initial intervals for successful reviews.

   Example:

     (setq gnosis-algorithm-interval '(0 1))

   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.


File: gnosis.info,  Node: Easiness Factor,  Next: Forgetting Factor,  Prev: Initial Interval,  Up: Gnosis Algorithm

5.2 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. 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, 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:

     (setq gnosis-algorithm-ef '(0.30 0.25 1.3))


File: gnosis.info,  Node: Forgetting Factor,  Prev: Easiness Factor,  Up: Gnosis Algorithm

5.3 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:

     (setq gnosis-algorithm-ff 0.5)

   You can set a custom ‘gnosis-algorithm-ff’ for each deck as well.


File: gnosis.info,  Node: Editing notes,  Next: Sync between devices,  Prev: Gnosis Algorithm,  Up: Top

6 Editing notes
***************

   • Currently there are 2 ways for editing notes:

        • You can edit a note after review by pressing ‘e’
        • Open ‘gnosis-dashboard’ with ‘M-x gnosis-dashboard’, find the
          note you want to edit and press ‘e’


File: gnosis.info,  Node: Sync between devices,  Next: Extending Gnosis,  Prev: Editing notes,  Up: Top

7 Sync between devices
**********************

Gnosis uses git to maintain data integrity and facilitate
synchronization across devices.

   You will need to configure your remote manually.

   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

   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:
     (setf gnosis-vc-auto-push t)
     (gnosis-vc-pull) ;; Run vc-pull for gnosis on startup


File: gnosis.info,  Node: Extending Gnosis,  Prev: Sync between devices,  Up: Top

8 Extending Gnosis
******************

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

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

* Menu:

* Creating Custom Note Types::


File: gnosis.info,  Node: Creating Custom Note Types,  Up: Extending Gnosis

8.1 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’

          (add-to-list 'gnosis-note-types "new-note-type")

   • 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



Tag Table:
Node: Top244
Node: Introduction1209
Node: Adding notes1851
Node: Note Types2220
Node: Cloze2432
Node: MCQ (Multiple Choice Question)3350
Node: Basic Type3846
Node: Double4149
Node: y-or-n4415
Node: Customization4817
Node: Image size5002
Node: Typos | String Comparison5288
Node: Gnosis Algorithm6063
Node: Initial Interval7099
Node: Easiness Factor7764
Node: Forgetting Factor8712
Node: Editing notes9320
Node: Sync between devices9712
Node: Extending Gnosis10740
Node: Creating Custom Note Types11195

End Tag Table


Local Variables:
coding: utf-8
End: