summaryrefslogtreecommitdiff
path: root/doc/gnosis.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gnosis.texi')
-rw-r--r--doc/gnosis.texi272
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