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

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

* Menu:

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

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



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

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


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

2 Installation
**************

Gnosis is available via MELPA
   • <https://melpa.org/#/gnosis>

* Menu:

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


File: gnosis.info,  Node: Using straightel,  Next: Installing manually from source,  Up: Installation

2.1 Using straight.el
=====================

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

   <https://github.com/radian-software/straight.el>

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

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


File: gnosis.info,  Node: Installing manually from source,  Prev: Using straightel,  Up: Installation

2.2 Installing manually from source
===================================

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

   • Clone gnosis repository

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

   • Add this to your emacs configuration

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


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

3 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’.  See more customization for *note Image Size: Image
size.


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

4 Note Types
************

* Menu:

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


File: gnosis.info,  Node: Cloze,  Next: Basic Type,  Up: Note Types

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


File: gnosis.info,  Node: Basic Type,  Next: Double,  Prev: Cloze,  Up: Note Types

4.2 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: MCQ (Multiple Choice Question),  Prev: Basic Type,  Up: Note Types

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


File: gnosis.info,  Node: MCQ (Multiple Choice Question),  Next: y-or-n,  Prev: Double,  Up: Note Types

4.4 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


File: gnosis.info,  Node: y-or-n,  Prev: MCQ (Multiple Choice Question),  Up: Note Types

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

5 Customization
***************

* Menu:

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


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

5.1 Image size
==============

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

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


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

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

6 Gnosis Algorithm
******************

* Menu:

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


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

6.1 Initial Interval
====================

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

   Example:

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

   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.


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

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

  4. How this is used:

   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:

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


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

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


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

7 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

8 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

9 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

9.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-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: Introduction1316
Node: Installation1796
Node: Using straightel2073
Node: Installing manually from source2585
Node: Adding notes3274
Node: Note Types3639
Node: Cloze3851
Node: Basic Type4824
Node: Double5102
Node: MCQ (Multiple Choice Question)5448
Node: y-or-n5857
Node: Customization6283
Node: Image size6468
Node: Typos | String Comparison6754
Node: Gnosis Algorithm7529
Node: Initial Interval7741
Node: Easiness Factor8248
Node: Forgetting Factor9153
Node: Editing notes9687
Node: Sync between devices10079
Node: Extending Gnosis11107
Node: Creating Custom Note Types11562

End Tag Table


Local Variables:
coding: utf-8
End: