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