summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/gnosis.info318
-rw-r--r--doc/gnosis.org217
-rw-r--r--doc/gnosis.texi272
3 files changed, 379 insertions, 428 deletions
diff --git a/doc/gnosis.info b/doc/gnosis.info
index 6bab4f5..69f63bc 100644
--- a/doc/gnosis.info
+++ b/doc/gnosis.info
@@ -12,19 +12,12 @@ 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. Notes are organized in a Question/Answer/Explanation format
-and reviewed at spaced intervals, determined by the success or failure
-to recall the answer.
+Gnosis 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.
- 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.
-
-This manual is written for Gnosis version 0.3.1, released on 2024-07-15.
+This manual is written for Gnosis version 0.4.0, released on 2024-08-7.
• Official manual: <https://thanosapollo.org/user-manual/gnosis>
• Git repositories:
@@ -39,15 +32,15 @@ This manual is written for Gnosis version 0.3.1, released on 2024-07-15.
* Gnosis Algorithm::
* Editing notes::
* Sync between devices::
-* Extending Gnosis::
+* Configuring Note Types::
-- The Detailed Node Listing --
Note Types
* Cloze::
-* MC-Cloze::
-* MCQ (Multiple Choice Question)::
+* MC-Cloze (Under development)::
+* MCQ::
* Basic Type::
* Double::
* y-or-n::
@@ -59,13 +52,14 @@ Customization
Gnosis Algorithm
-* Initial Interval::
-* Easiness Factor::
-* Forgetting Factor::
+* Anagnosis Event::
+* Proto::
-Extending Gnosis
+Configuring Note Types
+* Adjust Current Types Entries::
* Creating Custom Note Types::
+* Development::

@@ -74,19 +68,23 @@ File: gnosis.info, Node: Introduction, Next: Adding notes, Prev: Top, Up: To
1 Introduction
**************
-Before reading this manual, it's recommended you first try out
-‘gnosis-demo’
+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, 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 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 *note
+Gnosis Algorithm::
- 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::
+ Before continuing reading this manual, it's recommended you try out
+‘gnosis-demo’.

File: gnosis.info, Node: Adding notes, Next: Note Types, Prev: Introduction, Up: Top
@@ -98,6 +96,8 @@ Creating notes for gnosis can be done interactively with:
‘M-x gnosis-add-note’
+ Or from within ‘gnosis-dashboard’
+
When it comes to adding images, you can select images that are inside
‘gnosis-images-dir’. For adjusting image size, refer to *note
Customization::
@@ -111,14 +111,14 @@ File: gnosis.info, Node: Note Types, Next: Customization, Prev: Adding notes,
* Menu:
* Cloze::
-* MC-Cloze::
-* MCQ (Multiple Choice Question)::
+* MC-Cloze (Under development)::
+* MCQ::
* Basic Type::
* Double::
* y-or-n::

-File: gnosis.info, Node: Cloze, Next: MC-Cloze, Up: Note Types
+File: gnosis.info, Node: Cloze, Next: MC-Cloze (Under development), Up: Note Types
3.1 Cloze
=========
@@ -139,7 +139,11 @@ selecting ‘Cloze’, the question should be formatted like this:
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.
+ *UNIQUE* word, or a unique combination of words, in given note.
+
+ • If a cloze is repeated, such as in phrases with "acetyl" &
+ acetylcholine, include whitespace in the cloze to denote a
+ single word.
• You can use the keyword ‘::’ to indicate a hint.
@@ -147,12 +151,16 @@ selecting ‘Cloze’, the question should be formatted like this:
‘gnosis-cloze-guidance’.

-File: gnosis.info, Node: MC-Cloze, Next: MCQ (Multiple Choice Question), Prev: Cloze, Up: Note Types
+File: gnosis.info, Node: MC-Cloze (Under development), Next: MCQ, Prev: Cloze, Up: Note Types
+
+3.2 MC-Cloze (Under development)
+================================
+
+MC-Cloze is disabled by default, to enable it add to your configuration:
-3.2 MC-Cloze
-============
+ ‘(add-to-list 'gnosis-note-types "MC-Cloze")’
-A MC-Cloze (_Multiple Choice Cloze_) is a fill-in-the-blank note, but
+ A MC-Cloze (_Multiple Choice Cloze_) is a fill-in-the-blank note, but
unlike *note cloze note type: Cloze. the user is prompted to select an
option instead of typing an answer.
@@ -169,10 +177,10 @@ note will be generated from each cloze.
values that would mess up with regex functions.

-File: gnosis.info, Node: MCQ (Multiple Choice Question), Next: Basic Type, Prev: MC-Cloze, Up: Note Types
+File: gnosis.info, Node: MCQ, Next: Basic Type, Prev: MC-Cloze (Under development), Up: Note Types
-3.3 MCQ (Multiple Choice Question)
-==================================
+3.3 MCQ
+=======
A MCQ note type, as the name suggests, is a multiple choice question.
@@ -184,7 +192,7 @@ A MCQ note type, as the name suggests, is a multiple choice question.
‘gnosis-mcq-guidance’.

-File: gnosis.info, Node: Basic Type, Next: Double, Prev: MCQ (Multiple Choice Question), Up: Note Types
+File: gnosis.info, Node: Basic Type, Next: Double, Prev: MCQ, Up: Note Types
3.4 Basic Type
==============
@@ -267,101 +275,65 @@ File: gnosis.info, Node: Gnosis Algorithm, Next: Editing notes, Prev: Customi
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 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.
- 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’.
+ Gnosis has 2 special events, one is ‘anagnosis’ _ανάγνωση_ and
+‘lethe’ _λήθη_.
* 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.
-
- Upon failing to review a note without completing 2 successful
-reviews, you will have to review it again on the same day.
+* Anagnosis Event::
+* Proto::

-File: gnosis.info, Node: Easiness Factor, Next: Forgetting Factor, Prev: Initial Interval, Up: Gnosis Algorithm
+File: gnosis.info, Node: Anagnosis Event, Next: Proto, Up: Gnosis Algorithm
-5.2 Easiness Factor
+5.1 Anagnosis Event
===================
-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.
+‘Anagnosis’, which means comprehension & recognition of knowledge, is
+triggered when the consecutive successful or failed recalls are equal or
+greater to anagnosis value.
- 2. Easiness factor decrease value: Subtracted from the total easiness
- factor upon a failed review.
+ When ‘anagnosis’ is triggered by consecutive *successful* recalls,
+‘epignosis’ value is added to gnosis-plus. _Epignosis means accuracy of
+knowledge_.
- 3. Total Easiness factor: Used to calculate the next interval.
+ When ‘anagnosis’ is triggered by consecutive *failed* recalls,
+‘agnoia’ value is added to gnosis-minus. _Agnoia means lack of
+knowledge_
- 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))
+ You can set specific values for each deck and tag of the variables
+mentioned above by adjusting ‘gnosis-custom-values’.

-File: gnosis.info, Node: Forgetting Factor, Prev: Easiness Factor, Up: Gnosis Algorithm
+File: gnosis.info, Node: Proto, Prev: Anagnosis Event, Up: Gnosis Algorithm
-5.3 Forgetting Factor
-=====================
+5.2 Proto
+=========
-‘gnosis-algorithm-ff’ is a floating number below 1.
+The default initial interval is defined at ‘gnosis-algorithm-proto’, you
+can define a custom initial interval for each deck as well.
- Used to determine the next interval after an unsuccessful review.
+ ‘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.
- 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:
- Example configuration:
+ (setq gnosis-algorithm-interval '(0 1 2 30))
- (setq gnosis-algorithm-ff 0.5)
+ 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.
- You can set a custom ‘gnosis-algorithm-ff’ for each deck as well.
+ Upon failing to review a note without completing it's proto
+successful reviews, it's next review date will be on the same date.

File: gnosis.info, Node: Editing notes, Next: Sync between devices, Prev: Gnosis Algorithm, Up: Top
@@ -376,7 +348,7 @@ File: gnosis.info, Node: Editing notes, Next: Sync between devices, Prev: Gno
note you want to edit and press ‘e’

-File: gnosis.info, Node: Sync between devices, Next: Extending Gnosis, Prev: Editing notes, Up: Top
+File: gnosis.info, Node: Sync between devices, Next: Configuring Note Types, Prev: Editing notes, Up: Top
7 Sync between devices
**********************
@@ -405,78 +377,100 @@ your configuration:
(gnosis-vc-pull) ;; Run vc-pull for gnosis on startup

-File: gnosis.info, Node: Extending Gnosis, Prev: Sync between devices, Up: Top
+File: gnosis.info, Node: Configuring Note Types, 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?"
+8 Configuring Note Types
+************************
* Menu:
+* Adjust Current Types Entries::
* Creating Custom Note Types::
+* Development::

-File: gnosis.info, Node: Creating Custom Note Types, Up: Extending Gnosis
+File: gnosis.info, Node: Adjust Current Types Entries, Next: Creating Custom Note Types, Up: Configuring Note Types
+
+8.1 Adjust Current Types Entries
+================================
+
+Each gnosis note type has an _interactive_ function, named
+‘gnosis-add-note-TYPE’. You can set default values for each entry by
+hard coding specific values to their keywords.
+
+ For example:
+
+ (defun gnosis-add-note-basic (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)))
-8.1 Creating Custom Note Types
+ By evaluating the above code snippet, you won't be prompted to enter
+anything for ‘extra’ & ‘images’.
+
+
+File: gnosis.info, Node: Creating Custom Note Types, Next: Development, Prev: Adjust Current Types Entries, Up: Configuring Note Types
+
+8.2 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’
+ (add-to-list 'gnosis-note-types "NEW-TYPE")
+ • Create an interactive function
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.
+all the logic. You can use one of the ‘current gnosis-add-note--TYPE’
+functions or create one of your own.
Refer to ‘gnosis-add-note-basic’ & ‘gnosis-add-note--basic’ for a
-simple example of how this is done.
+simple example of how this is done, as well as ‘gnosis-add-note-double’.
- • Create ‘gnosis-review-TYPE’
+
+File: gnosis.info, Node: Development, Prev: Creating Custom Note Types, Up: Configuring Note Types
- 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.
+8.3 Development
+===============
- • Optionally, you might want to create your own custom
- ‘gnosis-display’ functions
+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?"

Tag Table:
Node: Top250
-Node: Introduction1614
-Node: Adding notes2341
-Node: Note Types2710
-Node: Cloze2935
-Node: MC-Cloze3913
-Node: MCQ (Multiple Choice Question)4737
-Node: Basic Type5236
-Node: Double5539
-Node: y-or-n5805
-Node: Customization6207
-Node: Image size6392
-Node: Typos | String Comparison6678
-Node: Gnosis Algorithm7453
-Node: Initial Interval8489
-Node: Easiness Factor9279
-Node: Forgetting Factor10227
-Node: Editing notes10835
-Node: Sync between devices11227
-Node: Extending Gnosis12248
-Node: Creating Custom Note Types12703
+Node: Introduction1350
+Node: Adding notes2363
+Node: Note Types2774
+Node: Cloze2992
+Node: MC-Cloze (Under development)4154
+Node: MCQ5142
+Node: Basic Type5580
+Node: Double5856
+Node: y-or-n6122
+Node: Customization6524
+Node: Image size6709
+Node: Typos | String Comparison6995
+Node: Gnosis Algorithm7770
+Node: Anagnosis Event8417
+Node: Proto9158
+Node: Editing notes9925
+Node: Sync between devices10317
+Node: Configuring Note Types11344
+Node: Adjust Current Types Entries11576
+Node: Creating Custom Note Types12576
+Node: Development13412

End Tag Table
diff --git a/doc/gnosis.org b/doc/gnosis.org
index dc2e1f5..15afc52 100644
--- a/doc/gnosis.org
+++ b/doc/gnosis.org
@@ -4,8 +4,8 @@
#+language: en
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
-#+macro: stable-version 0.3.1
-#+macro: release-date 2024-07-15
+#+macro: stable-version 0.4.0
+#+macro: release-date 2024-08-7
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
@@ -22,18 +22,10 @@
#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:[email protected],contact the maintainer}
-
-Gnosis (γνῶσις), pronounced "noh-sis", /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.
+Gnosis 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.
#+texinfo: @noindent
This manual is written for Gnosis version {{{stable-version}}}, released on {{{release-date}}}.
@@ -46,24 +38,31 @@ This manual is written for Gnosis version {{{stable-version}}}, released on {{{r
* Introduction
-Before reading this manual, it's recommended you first try out =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
+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
[[Gnosis Algorithm]]
+Before continuing reading this manual, it's recommended you try out
+=gnosis-demo=.
+
* Adding notes
Creating notes for gnosis can be done interactively with:
=M-x gnosis-add-note=
+Or from within =gnosis-dashboard=
+
When it comes to adding images, you can select images that are inside
=gnosis-images-dir=. For adjusting image size, refer to [[#Customization][Customization]]
@@ -88,14 +87,23 @@ You can also format clozes like Anki if you so prefer; e.g ~{{c1::Cyproheptadine
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.
+ *UNIQUE* word, or a unique combination of words, in given note.
+
+ + If a cloze is repeated, such as in phrases with "acetyl" &
+ acetylcholine, include whitespace in the cloze to denote a single
+ word.
+ You can use the keyword =::= to indicate a hint.
You can remove the /guidance/ string by adjusting
=gnosis-cloze-guidance=.
-** MC-Cloze
+** MC-Cloze (Under development)
+
+MC-Cloze is disabled by default, to enable it add to your configuration:
+
+ =(add-to-list 'gnosis-note-types "MC-Cloze")=
+
A MC-Cloze (/Multiple Choice Cloze/) is a fill-in-the-blank note,
but unlike [[#Cloze][cloze note type]] the user is prompted to select an option
instead of typing an answer.
@@ -113,7 +121,7 @@ Example:
When customizing =gnosis-mc-cloze=separator= pay attention to not use
values that would mess up with regex functions.
-** MCQ (Multiple Choice Question)
+** MCQ
A MCQ note type, as the name suggests, is a multiple choice question.
@@ -179,92 +187,51 @@ character."
* 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 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 ~anagnosis~ /ανάγνωση/ and ~lethe~ /λήθη/.
+** Anagnosis Event
+~Anagnosis~, which means comprehension & recognition of knowledge, is
+triggered when the consecutive successful or failed recalls are equal
+or greater to anagnosis value.
-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.
+When ~anagnosis~ is triggered by consecutive *successful* recalls,
+~epignosis~ value is added to gnosis-plus. /Epignosis means accuracy of knowledge/.
-You can customize deck specific algorithm values using =gnosis-dashboard=.
+When ~anagnosis~ is triggered by consecutive *failed* recalls,
+~agnoia~ value is added to gnosis-minus. /Agnoia means lack of knowledge/
-** Initial Interval
+You can set specific values for each deck and tag of the variables
+mentioned above by adjusting =gnosis-custom-values=.
+
+** Proto
The default initial interval is defined at
-=gnosis-algorithm-interval=, you can define a custom initial interval
+=gnosis-algorithm-proto=, 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.
+=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:
#+begin_src emacs-lisp
- (setq gnosis-algorithm-interval '(0 1))
-#+end_src
-
-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.
-
-** 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:
-
-#+begin_src emacs-lisp
- (setq gnosis-algorithm-ef '(0.30 0.25 1.3))
+ (setq gnosis-algorithm-interval '(0 1 2 30))
#+end_src
-** 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.
-
+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.
-Example configuration:
+Upon failing to review a note without completing it's proto successful reviews,
+it's next review date will be on the same date.
-#+begin_src emacs-lisp
- (setq gnosis-algorithm-ff 0.5)
-#+end_src
-
-You can set a custom =gnosis-algorithm-ff= for each deck as well.
* Editing notes
+ Currently there are 2 ways for editing notes:
@@ -300,14 +267,27 @@ To automatically push changes after a review session, add this to your configura
(gnosis-vc-pull) ;; Run vc-pull for gnosis on startup
#+end_src
-* 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.
+* Configuring Note Types
+** Adjust Current Types Entries
+Each gnosis note type has an /interactive/ function, named
+=gnosis-add-note-TYPE=. You can set default values for each entry by
+hard coding specific values to their keywords.
-To exit the testing environment, rerun =M-x gnosis-test-start= and
-then enter =n= (no) at the prompt "Start development env?"
+For example:
+
+#+begin_src emacs-lisp
+(defun gnosis-add-note-basic (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)))
+#+end_src
+By evaluating the above code snippet, you won't be prompted to enter
+anything for ~extra~ & ~images~.
** Creating Custom Note Types
Creating custom note types for gnosis is a fairly simple thing to do
@@ -315,23 +295,22 @@ Creating custom note types for gnosis is a fairly simple thing to do
+ First add your NEW-TYPE to =gnosis-note-types=
#+begin_src emacs-lisp
- (add-to-list 'gnosis-note-types "new-note-type")
+ (add-to-list 'gnosis-note-types "NEW-TYPE")
#+end_src
++ Create an interactive function
-+ 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.
+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. You can use one of the =current gnosis-add-note--TYPE=
+functions or create one of your own.
Refer to =gnosis-add-note-basic= & =gnosis-add-note--basic= for a simple
-example of how this is done.
+example of how this is done, as well as =gnosis-add-note-double=.
-+ 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.
+** Development
+To make development and customization easier, gnosis comes with
+=gnosis-test= module, that should be used to create a custom database for
+testing.
-+ Optionally, you might want to create your own custom =gnosis-display= functions
+To exit the testing environment, rerun =M-x gnosis-test-start= and
+then enter =n= (no) at the prompt "Start development env?"
diff --git a/doc/gnosis.texi b/doc/gnosis.texi
index b48163b..779ea47 100644
--- a/doc/gnosis.texi
+++ b/doc/gnosis.texi
@@ -25,20 +25,13 @@
@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.
+Gnosis 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.
@noindent
-This manual is written for Gnosis version 0.3.1, released on 2024-07-15.
+This manual is written for Gnosis version 0.4.0, released on 2024-08-7.
@itemize
@item
@@ -62,7 +55,7 @@ Git repositories:
* Gnosis Algorithm::
* Editing notes::
* Sync between devices::
-* Extending Gnosis::
+* Configuring Note Types::
@detailmenu
--- The Detailed Node Listing ---
@@ -70,8 +63,8 @@ Git repositories:
Note Types
* Cloze::
-* MC-Cloze::
-* MCQ (Multiple Choice Question)::
+* MC-Cloze (Under development)::
+* MCQ::
* Basic Type::
* Double::
* y-or-n::
@@ -83,13 +76,14 @@ Customization
Gnosis Algorithm
-* Initial Interval::
-* Easiness Factor::
-* Forgetting Factor::
+* Anagnosis Event::
+* Proto::
-Extending Gnosis
+Configuring Note Types
+* Adjust Current Types Entries::
* Creating Custom Note Types::
+* Development::
@end detailmenu
@end menu
@@ -97,19 +91,24 @@ Extending Gnosis
@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
+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
@@ -117,6 +116,8 @@ 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}
@@ -125,8 +126,8 @@ When it comes to adding images, you can select images that are inside
@menu
* Cloze::
-* MC-Cloze::
-* MCQ (Multiple Choice Question)::
+* MC-Cloze (Under development)::
+* MCQ::
* Basic Type::
* Double::
* y-or-n::
@@ -155,7 +156,14 @@ 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.
+@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.
@@ -164,8 +172,12 @@ You can use the keyword @samp{::} to indicate a hint.
You can remove the @emph{guidance} string by adjusting
@samp{gnosis-cloze-guidance}.
-@node MC-Cloze
-@section MC-Cloze
+@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
@@ -186,8 +198,8 @@ The greatest text editor is Emacs&&Vim&&Helix
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)
+@node MCQ
+@section MCQ
A MCQ note type, as the name suggests, is a multiple choice question.
@@ -265,106 +277,59 @@ 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.
+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.
-You can customize deck specific algorithm values using @samp{gnosis-dashboard}.
+Gnosis has 2 special events, one is @code{anagnosis} @emph{ανάγνωση} and @code{lethe} @emph{λήθη}.
@menu
-* Initial Interval::
-* Easiness Factor::
-* Forgetting Factor::
+* Anagnosis Event::
+* Proto::
@end menu
-@node Initial Interval
-@section Initial Interval
+@node Anagnosis Event
+@section Anagnosis Event
-The default initial interval is defined at
-@samp{gnosis-algorithm-interval}, you can define a custom initial interval
-for each deck as well.
+@code{Anagnosis}, which means comprehension & recognition of knowledge, is
+triggered when the consecutive successful or failed recalls are equal
+or greater to anagnosis value.
-@samp{gnosis-algorithm-interval} is a list of 2
-numbers, representing the first two initial intervals for successful
-reviews.
+When @code{anagnosis} is triggered by consecutive @strong{successful} recalls,
+@code{epignosis} value is added to gnosis-plus. @emph{Epignosis means accuracy of knowledge}.
-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
+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}.
-How this is used:
+@node Proto
+@section Proto
-Multiplies the last interval by the easiness factor after a successful
-review.
+The default initial interval is defined at
+@samp{gnosis-algorithm-proto}, you can define a custom initial interval
+for each deck as well.
-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>.
+@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.
-Configuration example:
+Example:
@lisp
-(setq gnosis-algorithm-ef '(0.30 0.25 1.3))
+(setq gnosis-algorithm-interval '(0 1 2 30))
@end lisp
-@node Forgetting Factor
-@section Forgetting Factor
-
-@samp{gnosis-algorithm-ff} is a floating number below 1.
+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.
-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.
+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
@@ -412,20 +377,38 @@ To automatically push changes after a review session, add this to your configura
(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?''
+@node Configuring Note Types
+@chapter Configuring Note Types
@menu
+* Adjust Current Types Entries::
* Creating Custom Note Types::
+* Development::
@end menu
+@node Adjust Current Types Entries
+@section Adjust Current Types Entries
+
+Each gnosis note type has an @emph{interactive} function, named
+@samp{gnosis-add-note-TYPE}. You can set default values for each entry by
+hard coding specific values to their keywords.
+
+For example:
+
+@lisp
+(defun gnosis-add-note-basic (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)))
+@end lisp
+
+By evaluating the above code snippet, you won't be prompted to enter
+anything for @code{extra} & @code{images}.
+
@node Creating Custom Note Types
@section Creating Custom Note Types
@@ -436,33 +419,28 @@ Creating custom note types for gnosis is a fairly simple thing to do
First add your NEW-TYPE to @samp{gnosis-note-types}
@lisp
-(add-to-list 'gnosis-note-types "new-note-type")
+(add-to-list 'gnosis-note-types "NEW-TYPE")
@end lisp
-
@item
-Create 2 functions; @samp{gnosis-add-note-TYPE} & @samp{gnosis-add-note--TYPE}
+Create an interactive function
@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.
+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. You can use one of the @samp{current gnosis-add-note--TYPE}
+functions or create one of your own.
Refer to @samp{gnosis-add-note-basic} & @samp{gnosis-add-note--basic} for a simple
-example of how this is done.
+example of how this is done, as well as @samp{gnosis-add-note-double}.
-@itemize
-@item
-Create @samp{gnosis-review-TYPE}
-@end itemize
+@node Development
+@section Development
-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.
+To make development and customization easier, gnosis comes with
+@samp{gnosis-test} module, that should be used to create a custom database for
+testing.
-@itemize
-@item
-Optionally, you might want to create your own custom @samp{gnosis-display} functions
-@end itemize
+To exit the testing environment, rerun @samp{M-x gnosis-test-start} and
+then enter @samp{n} (no) at the prompt ``Start development env?''
@bye