diff options
| -rw-r--r-- | doc/gnosis.info | 221 | ||||
| -rw-r--r-- | doc/gnosis.org | 124 | ||||
| -rw-r--r-- | doc/gnosis.texi | 151 | ||||
| -rw-r--r-- | gnosis.el | 41 |
4 files changed, 214 insertions, 323 deletions
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: <https://thanosapollo.org/user-manual/gnosis> • 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 - • <https://melpa.org/#/gnosis> - -* 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: - - <https://github.com/radian-software/straight.el> - - 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 <package> 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 + <increase-value>. 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 diff --git a/doc/gnosis.org b/doc/gnosis.org index 0571593..9ff58e8 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.1.9 -#+macro: release-date 2023-02-22 +#+macro: stable-version 0.2.0 +#+macro: release-date 2023-03-08 #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -36,51 +36,16 @@ This manual is written for Gnosis version {{{stable-version}}}, released on {{{r #+texinfo: @insertcopying * 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, 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 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. - -* Installation - -Gnosis is available via MELPA -+ <https://melpa.org/#/gnosis> - -** Using straight.el -If you have not installed straight.el, follow the instructions here: - - <https://github.com/radian-software/straight.el> - -Once you have installed straight.el, you can install gnosis using the -following emacs lisp snippet: - -#+begin_src emacs-lisp - (straight-use-package - '(gnosis :type git - :host nil - :repo "https://git.thanosapollo.org/gnosis")) -#+end_src - -** Installing manually from source -Gnosis depends on the ~compat~ & ~emacsql~ libraries which are available -from MELPA. Install them using ~M-x package-install RET <package> RET~ -or you may also install them manually from their repository. - -+ Clone gnosis repository - - #+begin_src shell - $ git clone https://git.thanosapollo.org/gnosis ~/.emacs.d/site-lisp/gnosis - #+end_src - -+ Add this to your emacs configuration - - #+begin_src emacs-lisp - (add-to-list 'load-path "~/.emacs.d/site-lisp/gnosis") - (load-file "~/.emacs.d/site-lisp/gnosis/gnosis.el") - #+end_src +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 Algorithm]] * Adding notes Creating notes for gnosis can be done interactively with: @@ -88,16 +53,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 [[Image size][Image Size]] +=gnosis-images-dir=. For adjusting image size, refer to [[Customization]] * Note Types ** 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: @@ -114,24 +76,18 @@ You can also format clozes like Anki if you prefer; e.g ~{{c1::Cyproheptadine}}~ + 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=. + ** 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. +The stem field (question) is separated by the options (choices) via +=gnosis-mcq-separator=, each option is separated by =gnosis-mcq-option-separator=. -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: -#+BEGIN_QUOTE - - Option 1 - - - Option 2 - - - {Correct choice} -#+END_QUOTE +You can remove the /guidance/ string by adjusting +=gnosis-mcq-guidance=. ** Basic Type @@ -144,8 +100,7 @@ input the answer. 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. ** y-or-n y-or-n (yes or no) note type, user is presented with a question and @@ -162,7 +117,7 @@ Adjust image size using =gnosis-image-height= & =gnosis-image-width= Example: #+begin_src emacs-lisp (setf gnosis-image-height 300 - gnosis-image-width 500) + gnosis-image-width 300) #+end_src ** Typos | String Comparison You can adjust =gnosis-string-difference=, this is a threshold value @@ -184,20 +139,42 @@ similar, considering that the latter involves just one additional 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 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=. + ** Initial Interval -=gnosis-algorithm-interval= is a list of 2 numbers, representing the -first two initial intervals for successful reviews. +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: #+begin_src emacs-lisp - (setq gnosis-algorithm-interval '(1 3)) + (setq gnosis-algorithm-interval '(0 1)) #+end_src 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. ** Easiness Factor @@ -245,6 +222,7 @@ Example configuration: (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: @@ -294,7 +272,7 @@ 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-type) + (add-to-list 'gnosis-note-types "new-note-type") #+end_src + Create 2 functions; =gnosis-add-note-TYPE= & =gnosis-add-note--TYPE= diff --git a/doc/gnosis.texi b/doc/gnosis.texi index a0e4af9..7f98492 100644 --- a/doc/gnosis.texi +++ b/doc/gnosis.texi @@ -30,7 +30,7 @@ a spaced repetition system implementation for note taking and self testing. @noindent -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. @itemize @item @@ -48,7 +48,6 @@ Git repositories: @menu * Introduction:: -* Installation:: * Adding notes:: * Note Types:: * Customization:: @@ -60,11 +59,6 @@ Git repositories: @detailmenu --- The Detailed Node Listing --- -Installation - -* Using straight.el: Using straightel. -* Installing manually from source:: - Note Types * Cloze:: @@ -94,68 +88,16 @@ Extending Gnosis @node Introduction @chapter 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. - -@node Installation -@chapter Installation - -Gnosis is available via MELPA -@itemize -@item -@uref{https://melpa.org/#/gnosis} -@end itemize - -@menu -* Using straight.el: Using straightel. -* Installing manually from source:: -@end menu - -@node Using straightel -@section Using straight.el - -If you have not installed straight.el, follow the instructions here: +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. -@uref{https://github.com/radian-software/straight.el} - -Once you have installed straight.el, you can install gnosis using the -following emacs lisp snippet: - -@lisp -(straight-use-package - '(gnosis :type git - :host nil - :repo "https://git.thanosapollo.org/gnosis")) -@end lisp - -@node Installing manually from source -@section Installing manually from source - -Gnosis depends on the @code{compat} & @code{emacsql} libraries which are available -from MELPA@. Install them using @code{M-x package-install RET <package> RET} -or you may also install them manually from their repository. - -@itemize -@item -Clone gnosis repository - -@example -$ git clone https://git.thanosapollo.org/gnosis ~/.emacs.d/site-lisp/gnosis -@end example - -@item -Add this to your emacs configuration - -@lisp -(add-to-list 'load-path "~/.emacs.d/site-lisp/gnosis") -(load-file "~/.emacs.d/site-lisp/gnosis/gnosis.el") -@end lisp -@end itemize +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 +@ref{Gnosis Algorithm} @node Adding notes @chapter Adding notes @@ -165,7 +107,7 @@ Creating notes for gnosis can be done interactively with: @samp{M-x gnosis-add-note} When it comes to adding images, you can select images that are inside -@samp{gnosis-images-dir}. For adjusting image size, refer to @ref{Image size, , Image Size} +@samp{gnosis-images-dir}. For adjusting image size, refer to @ref{Customization} @node Note Types @chapter Note Types @@ -182,10 +124,7 @@ When it comes to adding images, you can select images that are inside @section 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 @samp{M-x gnosis-add-note} and selecting @code{Cloze}, the question should be formatted like this: @@ -207,31 +146,19 @@ 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. @end itemize +You can remove the @emph{guidance} string by adjusting +@samp{gnosis-cloze-guidance}. + @node MCQ (Multiple Choice Question) @section 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 @samp{stem} field. - -Afterwards you will be prompted to enter the choices, each @samp{-} -indicates a choice, the choice inside @samp{@{@}} will be marked as the -correct one. - -Example of options: -@quotation -@itemize -@item -Option 1 - -@item -Option 2 - -@item -@{Correct choice@} -@end itemize +The stem field (question) is separated by the options (choices) via +@samp{gnosis-mcq-separator}, each option is separated by @samp{gnosis-mcq-option-separator}. -@end quotation +You can remove the @emph{guidance} string by adjusting +@samp{gnosis-mcq-guidance}. @node Basic Type @section Basic Type @@ -246,8 +173,7 @@ input the answer. 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. @node y-or-n @section y-or-n @@ -275,7 +201,7 @@ Adjust image size using @samp{gnosis-image-height} & @samp{gnosis-image-width} Example: @lisp (setf gnosis-image-height 300 - gnosis-image-width 500) + gnosis-image-width 300) @end lisp @node Typos | String Comparison @@ -302,6 +228,22 @@ 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. + +You can customize deck specific algorithm values using @samp{gnosis-dashboard}. + @menu * Initial Interval:: * Easiness Factor:: @@ -311,18 +253,23 @@ character.`` @node Initial Interval @section Initial Interval -@samp{gnosis-algorithm-interval} is a list of 2 numbers, representing the -first two initial intervals for successful reviews. +The default initial interval is defined at +@samp{gnosis-algorithm-interval}, you can define a custom initial interval +for each deck as well. + +@samp{gnosis-algorithm-interval} is a list of 2 +numbers, representing the first two initial intervals for successful +reviews. Example: @lisp -(setq gnosis-algorithm-interval '(1 3)) +(setq gnosis-algorithm-interval '(0 1)) @end lisp 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. @node Easiness Factor @section Easiness Factor @@ -377,6 +324,8 @@ Example configuration: (setq gnosis-algorithm-ff 0.5) @end lisp +You can set a custom @samp{gnosis-algorithm-ff} for each deck as well. + @node Editing notes @chapter Editing notes @@ -447,7 +396,7 @@ 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-type) +(add-to-list 'gnosis-note-types "new-note-type") @end lisp @item @@ -110,6 +110,9 @@ When nil, the image will be displayed at its original size." (make-directory gnosis-dir) (make-directory gnosis-images-dir)) +(defvar gnosis-db-file (expand-file-name "gnosis.db" gnosis-dir) + "Gnosis database file.") + (defconst gnosis-db (emacsql-sqlite-open (expand-file-name "gnosis.db" gnosis-dir)) "Gnosis database file.") @@ -135,21 +138,25 @@ When nil, the image will be displayed at its original size." - For each `cX`-tag there will be created a cloze type note, the above example creates 2 cloze type notes.)" . "") - "Guidance for cloze note type.") + "Guidance for cloze note type. + +car value is the prompt, cdr is the prewritten string.") (defvar gnosis-mcq-guidance '("Write question options after the `--'. Each `-' corresponds to an option\n-Example Option 1\n-{Correct Option}\nCorrect Option must be inside {}" . "Question\n--\n- Option\n- {Correct Option}") - "Guidance for MCQ note type.") + "Guidance for MCQ note type. + +car value is the prompt, cdr is the prewritten string.") -(defcustom gnosis-mcq-seperator "\n--\n" - "Seperator for stem field and options in mcq note type. +(defcustom gnosis-mcq-separator "\n--\n" + "Separator for stem field and options in mcq note type. Seperate the question/stem from options." :type 'string :group 'gnosis) -(defcustom gnosis-mcq-option-seperator "- " - "Seperator for options in mcq note type." +(defcustom gnosis-mcq-option-separator "-" + "Separator for options in mcq note type." :type 'string :group 'gnosis) @@ -172,9 +179,9 @@ Seperate the question/stem from options." "Face for the main section from note." :group 'gnosis-face-faces) -(defface gnosis-face-seperator +(defface gnosis-face-separator '((t :inherit warning)) - "Face for section seperator." + "Face for section separator." :group 'gnosis-face) (defface gnosis-face-directions @@ -323,7 +330,7 @@ SUCCESS is t when user-input is correct, else nil" (let ((hint (or hint ""))) (goto-char (point-max)) (insert - (propertize "\n\n-----\n" 'face 'gnosis-face-seperator) + (propertize "\n\n-----\n" 'face 'gnosis-face-separator) (propertize hint 'face 'gnosis-face-hint)))) (cl-defun gnosis-display-cloze-reveal (&key (cloze-char gnosis-cloze-string) replace (success t) (face nil)) @@ -382,7 +389,7 @@ Refer to `gnosis-db-schema-extras' for more." "Display extra information & extra-image for note ID." (let ((extras (or (gnosis-get 'extra-notes 'extras `(= id ,id)) ""))) (goto-char (point-max)) - (insert (propertize "\n\n-----\n" 'face 'gnosis-face-seperator)) + (insert (propertize "\n\n-----\n" 'face 'gnosis-face-separator)) (gnosis-display-image id 'extra-image) (fill-paragraph (insert "\n" (propertize extras 'face 'gnosis-face-extra))))) @@ -538,8 +545,8 @@ is the image to display post review Prompt user for input to create a note of type `MCQ'. -Stem field is seperated from options by `gnosis-mcq-seperator', and -each option is seperated by `gnosis-mcq-option-seperator'. The correct +Stem field is seperated from options by `gnosis-mcq-separator', and +each option is seperated by `gnosis-mcq-option-separator'. The correct answer is surrounded by curly braces, e.g {Correct Answer}. Refer to `gnosis-add-note--mcq' & `gnosis-prompt-mcq-input' for more." @@ -862,7 +869,7 @@ Optionally, add cusotm PROMPT." "Return note ID's for every note with INPUT-TAGS." (unless (listp input-tags) (error "`input-tags' need to be a list")) - (cl-loop for (id tags) in (emacsql gnosis-db [:select [id tags] :from notes]) + (cl-loop for (id tags) in (gnosis-select '[id tags] 'notes) when (and (cl-every (lambda (tag) (member tag tags)) input-tags) (not (gnosis-suspended-p id))) collect id)) @@ -933,13 +940,13 @@ default value." Return a list of the form ((QUESTION CHOICES) CORRECT-CHOICE-INDEX)." (let ((user-input (read-string-from-buffer (or (car gnosis-mcq-guidance) "") (or (cdr gnosis-mcq-guidance) "")))) - (unless (string-match-p gnosis-mcq-seperator user-input) - (error "Seperator %s not found" gnosis-mcq-seperator)) - (let* ((input-seperated (split-string user-input gnosis-mcq-seperator t "[\s\n]")) + (unless (string-match-p gnosis-mcq-separator user-input) + (error "Separator %s not found" gnosis-mcq-separator)) + (let* ((input-seperated (split-string user-input gnosis-mcq-separator t "[\s\n]")) (stem (car input-seperated)) (input (split-string (mapconcat 'identity (cdr input-seperated) "\n") - gnosis-mcq-option-seperator t "[\s\n]")) + gnosis-mcq-option-separator t "[\s\n]")) (correct-choice-index (or (cl-position-if (lambda (string) (string-match "{.*}" string)) input) (error "Correct choice not found. Use {} to indicate the correct option"))) |