From 741acfcb4c35359e8975f65ba1e16eb0d981c874 Mon Sep 17 00:00:00 2001 From: Thanos Apollo Date: Wed, 7 Aug 2024 14:30:13 +0300 Subject: Update docs for version 0.4.0 --- doc/gnosis.info | 318 +++++++++++++++++++++++++++----------------------------- 1 file changed, 156 insertions(+), 162 deletions(-) (limited to 'doc/gnosis.info') 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: • 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 + . - - 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 -- cgit v1.2.3