From d09057b49e1fdf3d993e054c688baa3dc2d46efc Mon Sep 17 00:00:00 2001 From: Thanos Apollo Date: Fri, 8 Mar 2024 09:24:03 +0200 Subject: Update doc & fix typos --- doc/gnosis.info | 221 +++++++++++++++++++++++--------------------------------- 1 file changed, 89 insertions(+), 132 deletions(-) (limited to 'doc/gnosis.info') diff --git a/doc/gnosis.info b/doc/gnosis.info index 5e5f7c5..885f23d 100644 --- a/doc/gnosis.info +++ b/doc/gnosis.info @@ -15,7 +15,7 @@ Gnosis (γνῶσις), pronounced "noh-sis", _meaning knowledge in Greek_, is a spaced repetition system implementation for note taking and self testing. -This manual is written for Gnosis version 0.1.9, released on 2023-02-22. +This manual is written for Gnosis version 0.2.0, released on 2023-03-08. • Official manual: • Git repositories: @@ -24,7 +24,6 @@ This manual is written for Gnosis version 0.1.9, released on 2023-02-22. * Menu: * Introduction:: -* Installation:: * Adding notes:: * Note Types:: * Customization:: @@ -35,11 +34,6 @@ This manual is written for Gnosis version 0.1.9, released on 2023-02-22. -- The Detailed Node Listing -- -Installation - -* Using straight.el: Using straightel. -* Installing manually from source:: - Note Types * Cloze:: @@ -65,74 +59,26 @@ Extending Gnosis  -File: gnosis.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top +File: gnosis.info, Node: Introduction, Next: Adding notes, Prev: Top, Up: Top 1 Introduction ************** -Gnosis is a spaced repetition note taking and self testing system, where -notes are taken in a Question/Answer/Explanation-like format & reviewed -in spaced intervals. - - Gnosis can help you better understand and retain the material by -encouraging active engagement. It also provides a clear structure for -your notes & review sessions, making it easier to study. - - -File: gnosis.info, Node: Installation, Next: Adding notes, Prev: Introduction, Up: Top - -2 Installation -************** - -Gnosis is available via MELPA - • - -* Menu: - -* Using straight.el: Using straightel. -* Installing manually from source:: - - -File: gnosis.info, Node: Using straightel, Next: Installing manually from source, Up: Installation - -2.1 Using straight.el -===================== - -If you have not installed straight.el, follow the instructions here: - - - - Once you have installed straight.el, you can install gnosis using the -following emacs lisp snippet: +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. - (straight-use-package - '(gnosis :type git - :host nil - :repo "https://git.thanosapollo.org/gnosis")) + 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::  -File: gnosis.info, Node: Installing manually from source, Prev: Using straightel, Up: Installation +File: gnosis.info, Node: Adding notes, Next: Note Types, Prev: Introduction, Up: Top -2.2 Installing manually from source -=================================== - -Gnosis depends on the ‘compat’ & ‘emacsql’ libraries which are available -from MELPA. Install them using ‘M-x package-install RET RET’ -or you may also install them manually from their repository. - - • Clone gnosis repository - - $ git clone https://git.thanosapollo.org/gnosis ~/.emacs.d/site-lisp/gnosis - - • Add this to your emacs configuration - - (add-to-list 'load-path "~/.emacs.d/site-lisp/gnosis") - (load-file "~/.emacs.d/site-lisp/gnosis/gnosis.el") - - -File: gnosis.info, Node: Adding notes, Next: Note Types, Prev: Installation, Up: Top - -3 Adding notes +2 Adding notes ************** Creating notes for gnosis can be done interactively with: @@ -140,13 +86,13 @@ Creating notes for gnosis can be done interactively with: ‘M-x gnosis-add-note’ When it comes to adding images, you can select images that are inside -‘gnosis-images-dir’. For adjusting image size, refer to *note Image -Size: Image size. +‘gnosis-images-dir’. For adjusting image size, refer to *note +Customization::  File: gnosis.info, Node: Note Types, Next: Customization, Prev: Adding notes, Up: Top -4 Note Types +3 Note Types ************ * Menu: @@ -160,15 +106,11 @@ File: gnosis.info, Node: Note Types, Next: Customization, Prev: Adding notes,  File: gnosis.info, Node: Cloze, Next: MCQ (Multiple Choice Question), Up: Note Types -4.1 Cloze +3.1 Cloze ========= A cloze note type is a format where you create sentences or paragraphs -with "missing" words. Almost all note types can be written as a cloze -type in a way. Ideal type for memorizing definitions. - - To get the most out of gnosis, you have to become familiar with cloze -type notes. +with "missing" words. A fill-in-the-blanks question. You can create a cloze note type using ‘M-x gnosis-add-note’ and selecting ‘Cloze’, the question should be formatted like this: @@ -185,31 +127,28 @@ selecting ‘Cloze’, the question should be formatted like this: • Each 'cX' tag can have multiple clozes, but each cloze must be a *UNIQUE* word (or a unique combination of words) in given note. + You can remove the _guidance_ string by adjusting +‘gnosis-cloze-guidance’. +  File: gnosis.info, Node: MCQ (Multiple Choice Question), Next: Basic Type, Prev: Cloze, Up: Note Types -4.2 MCQ (Multiple Choice Question) +3.2 MCQ (Multiple Choice Question) ================================== A MCQ note type, as the name suggests, is a multiple choice question. - First you will be prompted to input the question ‘stem’ field. - - Afterwards you will be prompted to enter the choices, each ‘-’ -indicates a choice, the choice inside ‘{}’ will be marked as the correct -one. - - Example of options: - • Option 1 + The stem field (question) is separated by the options (choices) via +‘gnosis-mcq-separator’, each option is separated by +‘gnosis-mcq-option-separator’. - • Option 2 - - • {Correct choice} + You can remove the _guidance_ string by adjusting +‘gnosis-mcq-guidance’.  File: gnosis.info, Node: Basic Type, Next: Double, Prev: MCQ (Multiple Choice Question), Up: Note Types -4.3 Basic Type +3.3 Basic Type ============== Basic note type is a simple question/answer note, where the user first @@ -219,19 +158,18 @@ input the answer.  File: gnosis.info, Node: Double, Next: y-or-n, Prev: Basic Type, Up: Note Types -4.4 Double +3.4 Double ========== Double note type, is essentially a note that generates 2 basic notes. The second one reverses question/answer. - Ideal for vocabulary acquisition, creating vocabulary/translation -notes for a foreign language. + Ideal for vocabulary acquisition notes.  File: gnosis.info, Node: y-or-n, Prev: Double, Up: Note Types -4.5 y-or-n +3.5 y-or-n ========== y-or-n (yes or no) note type, user is presented with a question and @@ -244,7 +182,7 @@ the character values used to represent them.  File: gnosis.info, Node: Customization, Next: Gnosis Algorithm, Prev: Note Types, Up: Top -5 Customization +4 Customization *************** * Menu: @@ -255,19 +193,19 @@ File: gnosis.info, Node: Customization, Next: Gnosis Algorithm, Prev: Note Ty  File: gnosis.info, Node: Image size, Next: Typos | String Comparison, Up: Customization -5.1 Image size +4.1 Image size ============== Adjust image size using ‘gnosis-image-height’ & ‘gnosis-image-width’ Example: (setf gnosis-image-height 300 - gnosis-image-width 500) + gnosis-image-width 300)  File: gnosis.info, Node: Typos | String Comparison, Prev: Image size, Up: Customization -5.2 Typos | String Comparison +4.2 Typos | String Comparison ============================= You can adjust ‘gnosis-string-difference’, this is a threshold value for @@ -288,9 +226,26 @@ character."  File: gnosis.info, Node: Gnosis Algorithm, Next: Editing notes, Prev: Customization, Up: Top -6 Gnosis Algorithm +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 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’. + * Menu: * Initial Interval:: @@ -300,24 +255,27 @@ File: gnosis.info, Node: Gnosis Algorithm, Next: Editing notes, Prev: Customi  File: gnosis.info, Node: Initial Interval, Next: Easiness Factor, Up: Gnosis Algorithm -6.1 Initial Interval +5.1 Initial Interval ==================== -‘gnosis-algorithm-interval’ is a list of 2 numbers, representing the +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 '(1 3)) + (setq gnosis-algorithm-interval '(0 1)) Using the above example, after first successfully reviewing a note, -you will see it again tomorrow, if you successfully review said note -again, the next review will be after 3 days. +you will see it again in the next review session, if you successfully +review said note again, the next review will be tomorrow.  File: gnosis.info, Node: Easiness Factor, Next: Forgetting Factor, Prev: Initial Interval, Up: Gnosis Algorithm -6.2 Easiness Factor +5.2 Easiness Factor =================== The ‘gnosis-algorithm-ef’ is a list that consists of three items: @@ -347,7 +305,7 @@ updated by adding the increase value 2.0 + .  File: gnosis.info, Node: Forgetting Factor, Prev: Easiness Factor, Up: Gnosis Algorithm -6.3 Forgetting Factor +5.3 Forgetting Factor ===================== ‘gnosis-algorithm-ff’ is a floating number below 1. @@ -362,10 +320,12 @@ interval was 6 days, the next interval will be 6 * 0.5 = 3 days. (setq gnosis-algorithm-ff 0.5) + You can set a custom ‘gnosis-algorithm-ff’ for each deck as well. +  File: gnosis.info, Node: Editing notes, Next: Sync between devices, Prev: Gnosis Algorithm, Up: Top -7 Editing notes +6 Editing notes *************** • Currently there are 2 ways for editing notes: @@ -377,7 +337,7 @@ File: gnosis.info, Node: Editing notes, Next: Sync between devices, Prev: Gno  File: gnosis.info, Node: Sync between devices, Next: Extending Gnosis, Prev: Editing notes, Up: Top -8 Sync between devices +7 Sync between devices ********************** Gnosis uses git to maintain data integrity and facilitate @@ -406,7 +366,7 @@ your configuration:  File: gnosis.info, Node: Extending Gnosis, Prev: Sync between devices, Up: Top -9 Extending Gnosis +8 Extending Gnosis ****************** To make development and customization easier, gnosis comes with @@ -423,14 +383,14 @@ then enter ‘n’ (no) at the prompt "Start development env?"  File: gnosis.info, Node: Creating Custom Note Types, Up: Extending Gnosis -9.1 Creating Custom Note Types +8.1 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-type) + (add-to-list 'gnosis-note-types "new-note-type") • Create 2 functions; ‘gnosis-add-note-TYPE’ & ‘gnosis-add-note--TYPE’ @@ -456,28 +416,25 @@ should be done.  Tag Table: Node: Top244 -Node: Introduction1316 -Node: Installation1796 -Node: Using straightel2073 -Node: Installing manually from source2585 -Node: Adding notes3274 -Node: Note Types3651 -Node: Cloze3863 -Node: MCQ (Multiple Choice Question)4856 -Node: Basic Type5429 -Node: Double5732 -Node: y-or-n6054 -Node: Customization6456 -Node: Image size6641 -Node: Typos | String Comparison6927 -Node: Gnosis Algorithm7702 -Node: Initial Interval7914 -Node: Easiness Factor8421 -Node: Forgetting Factor9369 -Node: Editing notes9903 -Node: Sync between devices10295 -Node: Extending Gnosis11323 -Node: Creating Custom Note Types11778 +Node: Introduction1209 +Node: Adding notes1851 +Node: Note Types2220 +Node: Cloze2432 +Node: MCQ (Multiple Choice Question)3350 +Node: Basic Type3846 +Node: Double4149 +Node: y-or-n4415 +Node: Customization4817 +Node: Image size5002 +Node: Typos | String Comparison5288 +Node: Gnosis Algorithm6063 +Node: Initial Interval7099 +Node: Easiness Factor7764 +Node: Forgetting Factor8712 +Node: Editing notes9320 +Node: Sync between devices9712 +Node: Extending Gnosis10740 +Node: Creating Custom Note Types11195  End Tag Table -- cgit v1.2.3