Release version 0.4.00.4.0

* Major rewrite on gnosis algorithm.
  * Add gnosis-score
  * Add epignosis and agnoia
  * Add lethe and anagnosis events
    * Anagnosis events adjust gnosis-score
      depending on review performance, using epignosis
      and agnoia
    * Lethe resets next interval to 0
  * Refactor calculations of next interval and gnosis-score
* Add custom variables for tags and decks, configured using emacs
  lisp.
* Rewrite gnosis database.
  * Remove deck specific values.
  * Use new algorithm variables.

1 files changed, 125 insertions, 147 deletions

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