diff options
Diffstat (limited to 'doc/gnosis.texi')
| -rw-r--r-- | doc/gnosis.texi | 272 |
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 |