diff options
| -rw-r--r-- | doc/gnosis.info | 106 | ||||
| -rw-r--r-- | doc/gnosis.org | 49 | ||||
| -rw-r--r-- | doc/gnosis.texi | 60 | ||||
| -rw-r--r-- | gnosis.el | 83 |
4 files changed, 182 insertions, 116 deletions
diff --git a/doc/gnosis.info b/doc/gnosis.info index 5176ec6..5e5f7c5 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.8, released on 2023-02-21. +This manual is written for Gnosis version 0.1.9, released on 2023-02-22. • Official manual: <https://thanosapollo.org/user-manual/gnosis> • Git repositories: @@ -43,9 +43,9 @@ Installation Note Types * Cloze:: +* MCQ (Multiple Choice Question):: * Basic Type:: * Double:: -* MCQ (Multiple Choice Question):: * y-or-n:: Customization @@ -135,12 +135,13 @@ File: gnosis.info, Node: Adding notes, Next: Note Types, Prev: Installation, 3 Adding notes ************** -Creating notes for gnosis can be done interactively with: ‘M-x -gnosis-add-note’ +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’. See more customization for *note Image Size: Image -size. +‘gnosis-images-dir’. For adjusting image size, refer to *note Image +Size: Image size. File: gnosis.info, Node: Note Types, Next: Customization, Prev: Adding notes, Up: Top @@ -151,13 +152,13 @@ File: gnosis.info, Node: Note Types, Next: Customization, Prev: Adding notes, * Menu: * Cloze:: +* MCQ (Multiple Choice Question):: * Basic Type:: * Double:: -* MCQ (Multiple Choice Question):: * y-or-n:: -File: gnosis.info, Node: Cloze, Next: Basic Type, Up: Note Types +File: gnosis.info, Node: Cloze, Next: MCQ (Multiple Choice Question), Up: Note Types 4.1 Cloze ========= @@ -185,9 +186,30 @@ selecting ‘Cloze’, the question should be formatted like this: *UNIQUE* word (or a unique combination of words) in given note. -File: gnosis.info, Node: Basic Type, Next: Double, Prev: Cloze, Up: Note Types +File: gnosis.info, Node: MCQ (Multiple Choice Question), Next: Basic Type, Prev: Cloze, Up: Note Types + +4.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 + + • Option 2 + + • {Correct choice} + + +File: gnosis.info, Node: Basic Type, Next: Double, Prev: MCQ (Multiple Choice Question), Up: Note Types -4.2 Basic Type +4.3 Basic Type ============== Basic note type is a simple question/answer note, where the user first @@ -195,9 +217,9 @@ sees a "main" part, which is usually a question, and he is prompted to input the answer. -File: gnosis.info, Node: Double, Next: MCQ (Multiple Choice Question), Prev: Basic Type, Up: Note Types +File: gnosis.info, Node: Double, Next: y-or-n, Prev: Basic Type, Up: Note Types -4.3 Double +4.4 Double ========== Double note type, is essentially a note that generates 2 basic notes. @@ -207,20 +229,7 @@ The second one reverses question/answer. notes for a foreign language. -File: gnosis.info, Node: MCQ (Multiple Choice Question), Next: y-or-n, Prev: Double, Up: Note Types - -4.4 MCQ (Multiple Choice Question) -================================== - -MCQ note type, consists of a "stem" part that is displayed, and -"options" for the user to select the right one. - - Answer must be the index NUMBER of the correct answer from OPTIONS. - - Ideal for self testing & simulating exams - - -File: gnosis.info, Node: y-or-n, Prev: MCQ (Multiple Choice Question), Up: Note Types +File: gnosis.info, Node: y-or-n, Prev: Double, Up: Note Types 4.5 y-or-n ========== @@ -319,16 +328,17 @@ The ‘gnosis-algorithm-ef’ is a list that consists of three items: 2. Easiness factor decrease value: Subtracted from the total easiness factor upon a failed review. - 3. Initial total easiness factor: Used to calculate the next interval. + 3. Total Easiness factor: Used to calculate the next interval. - 4. How this is used: + How this is used: Multiplies the last interval by the easiness factor after a successful review. - For example, 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 -total easiness factor would be updated by adding the increase factor. + 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: @@ -451,23 +461,23 @@ Node: Installation1796 Node: Using straightel2073 Node: Installing manually from source2585 Node: Adding notes3274 -Node: Note Types3639 -Node: Cloze3851 -Node: Basic Type4824 -Node: Double5102 -Node: MCQ (Multiple Choice Question)5448 -Node: y-or-n5857 -Node: Customization6283 -Node: Image size6468 -Node: Typos | String Comparison6754 -Node: Gnosis Algorithm7529 -Node: Initial Interval7741 -Node: Easiness Factor8248 -Node: Forgetting Factor9153 -Node: Editing notes9687 -Node: Sync between devices10079 -Node: Extending Gnosis11107 -Node: Creating Custom Note Types11562 +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 End Tag Table diff --git a/doc/gnosis.org b/doc/gnosis.org index 16d4a15..0571593 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.8 -#+macro: release-date 2023-02-21 +#+macro: stable-version 0.1.9 +#+macro: release-date 2023-02-22 #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -84,10 +84,11 @@ or you may also install them manually from their repository. * Adding notes Creating notes for gnosis can be done interactively with: - =M-x gnosis-add-note= + + =M-x gnosis-add-note= When it comes to adding images, you can select images that are inside -=gnosis-images-dir=. See more customization for [[Image size][Image Size]] +=gnosis-images-dir=. For adjusting image size, refer to [[Image size][Image Size]] * Note Types ** Cloze @@ -113,6 +114,26 @@ 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. +** 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: +#+BEGIN_QUOTE + - Option 1 + + - Option 2 + + - {Correct choice} +#+END_QUOTE + + ** Basic Type Basic note type is a simple question/answer note, where the user first @@ -126,14 +147,6 @@ The second one reverses question/answer. Ideal for vocabulary acquisition, creating vocabulary/translation notes for a foreign language. -** MCQ (Multiple Choice Question) -MCQ note type, consists of a "stem" part that is displayed, and -"options" for the user to select the right one. - -Answer must be the index NUMBER of the correct answer from OPTIONS. - -Ideal for self testing & simulating exams - ** y-or-n y-or-n (yes or no) note type, user is presented with a question and prompted to enter character "y" or "n". @@ -196,16 +209,18 @@ The =gnosis-algorithm-ef= is a list that consists of three items: 2. Easiness factor decrease value: Subtracted from the total easiness factor upon a failed review. -3. Initial total easiness factor: Used to calculate the next interval. +3. Total Easiness factor: Used to calculate the next interval. + -+ How this is used: +How this is used: Multiplies the last interval by the easiness factor after a successful review. -For example, 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 -total easiness factor would be updated by adding the increase factor. +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: diff --git a/doc/gnosis.texi b/doc/gnosis.texi index 745f7ff..a0e4af9 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.8, released on 2023-02-21. +This manual is written for Gnosis version 0.1.9, released on 2023-02-22. @itemize @item @@ -68,9 +68,9 @@ Installation Note Types * Cloze:: +* MCQ (Multiple Choice Question):: * Basic Type:: * Double:: -* MCQ (Multiple Choice Question):: * y-or-n:: Customization @@ -161,19 +161,20 @@ Add this to your emacs configuration @chapter Adding notes Creating notes for gnosis can be done interactively with: - @samp{M-x gnosis-add-note} + +@samp{M-x gnosis-add-note} When it comes to adding images, you can select images that are inside -@samp{gnosis-images-dir}. See more customization for @ref{Image size, , Image Size} +@samp{gnosis-images-dir}. For adjusting image size, refer to @ref{Image size, , Image Size} @node Note Types @chapter Note Types @menu * Cloze:: +* MCQ (Multiple Choice Question):: * Basic Type:: * Double:: -* MCQ (Multiple Choice Question):: * y-or-n:: @end menu @@ -206,6 +207,32 @@ 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 +@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 + +@end quotation + @node Basic Type @section Basic Type @@ -222,16 +249,6 @@ The second one reverses question/answer. Ideal for vocabulary acquisition, creating vocabulary/translation notes for a foreign language. -@node MCQ (Multiple Choice Question) -@section MCQ (Multiple Choice Question) - -MCQ note type, consists of a ``stem'' part that is displayed, and -``options'' for the user to select the right one. - -Answer must be the index NUMBER of the correct answer from OPTIONS@. - -Ideal for self testing & simulating exams - @node y-or-n @section y-or-n @@ -322,18 +339,19 @@ Easiness factor decrease value: Subtracted from the total easiness factor upon a failed review. @item -Initial total easiness factor: Used to calculate the next interval. +Total Easiness factor: Used to calculate the next interval. +@end enumerate + -@item How this is used: -@end enumerate Multiplies the last interval by the easiness factor after a successful review. -For example, 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 -total easiness factor would be updated by adding the increase factor. +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: @@ -5,7 +5,7 @@ ;; Author: Thanos Apollo <[email protected]> ;; Keywords: extensions ;; URL: https://thanosapollo.org/projects/gnosis -;; Version: 0.1.8 +;; Version: 0.1.9 ;; Package-Requires: ((emacs "27.2") (compat "29.1.4.2") (emacsql "20240124")) @@ -125,7 +125,7 @@ When nil, the image will be displayed at its original size." (defvar gnosis-previous-note-tags '() "Tags input from previously added note.") -(defvar gnosis-previous-hint nil +(defvar gnosis-previous-note-hint nil "Hint input from previously added note.") ;;; Faces @@ -436,7 +436,6 @@ When called with a prefix, unsuspends all notes for tag." ("Tag" (gnosis-suspend-tag)) (_ (message "Not ready yet."))))) - (defun gnosis-add-note-fields (deck type main options answer extra tags suspend image second-image) "Insert fields for new note. @@ -505,13 +504,17 @@ TAGS: Used to organize notes Refer to `gnosis-add-note--mcq' for more." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `MCQ' to `%s' deck? " deck)) - (gnosis-add-note--mcq :deck deck - :question (read-string "Question: ") - :choices (gnosis--prompt "Choices") - :correct-answer (string-to-number (read-string "Which is the correct answer (number)? ")) - :extra (read-string "Extra: ") - :image (gnosis-select-image) - :tags (gnosis-tag-prompt))))) + (let* ((stem (read-string-from-buffer "Question: " "")) + (input-choices (gnosis-prompt-mcq-choices)) + (choices (car input-choices)) + (correct-choice (cadr input-choices))) + (gnosis-add-note--mcq :deck deck + :question stem + :choices choices + :correct-answer correct-choice + :extra (read-string-from-buffer "Extra" "") + :image (gnosis-select-image) + :tags (gnosis-prompt-tags--split gnosis-previous-note-tags)))))) (cl-defun gnosis-add-note--basic (&key deck question hint answer extra (image nil) tags (suspend 0) (second-image nil)) @@ -538,12 +541,12 @@ Refer to `gnosis-add-note--basic' for more." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `basic' to `%s' deck? " deck)) (gnosis-add-note--basic :deck deck - :question (read-string "Question: ") + :question (read-string-from-buffer "Question: " "") :answer (read-string "Answer: ") - :hint (gnosis-hint-prompt gnosis-previous-hint) - :extra (read-string "Extra: ") + :hint (gnosis-hint-prompt gnosis-previous-note-hint) + :extra (read-string-from-buffer "Extra: " "") :image (gnosis-select-image) - :tags (gnosis-tag-prompt))))) + :tags (gnosis-prompt-tags--split gnosis-previous-note-tags))))) (cl-defun gnosis-add-note--double (&key deck question hint answer extra (image nil) tags (suspend 0) (second-image nil)) "Add Double type note. @@ -574,13 +577,10 @@ Refer to `gnosis-add-note--double' for more." (gnosis-add-note--double :deck deck :question (read-string "Question: ") :answer (read-string "Answer: ") - :image (when (y-or-n-p "Add image to display during review?") - (funcall gnosis-completing-read-function "Select image: " - (gnosis-directory-files))) - :hint (gnosis-hint-prompt gnosis-previous-hint) - :extra (read-string "Extra: ") - :image (gnosis-select-image) - :tags (gnosis-tag-prompt))))) + :hint (gnosis-hint-prompt gnosis-previous-note-hint) + :extra (read-string-from-buffer "Extra" "") + :image (gnosis-select-image "Add image to display during review?") + :tags (gnosis-prompt-tags--split gnosis-previous-note-tags))))) (cl-defun gnosis-add-note--y-or-n (&key deck question hint answer extra (image nil) tags (suspend 0) (second-image nil)) "Add y-or-n type note. @@ -604,12 +604,12 @@ refer to `gnosis-add-note--y-or-n' for more information about keyword values." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `y-or-n' to `%s' deck? " deck)) (gnosis-add-note--y-or-n :deck deck - :question (read-string "Question: ") + :question (read-string-from-buffer "Question: " "") :answer (read-char-choice "Answer: [y] or [n]? " '(?y ?n)) - :hint (gnosis-hint-prompt gnosis-previous-hint) - :extra (read-string "Extra: ") + :hint (gnosis-hint-prompt gnosis-previous-note-hint) + :extra (read-string-from-buffer "Extra" "") :image (gnosis-select-image) - :tags (gnosis-tag-prompt))))) + :tags (gnosis-prompt-tags--split gnosis-previous-note-tags))))) (cl-defun gnosis-add-note--cloze (&key deck note hint tags (suspend 0) extra (image nil) (second-image nil)) @@ -678,11 +678,14 @@ See `gnosis-add-note--cloze' for more reference." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `cloze' to `%s' deck? " deck)) (gnosis-add-note--cloze :deck deck - :note (read-string "Question: ") - :hint (gnosis-hint-prompt gnosis-previous-hint) - :extra (read-string "Extra: ") + :note (read-string-from-buffer "Cloze questions are formatted like this:\{c1:Cyproheptadine} is a(n) {c2:5-HT2} receptor antagonist used to treat {c2:serotonin syndrome} + +- For each `cX`-tag there will be created a cloze type note, the above + example creates 2 cloze type notes." "") + :hint (gnosis-hint-prompt gnosis-previous-note-hint) + :extra (read-string-from-buffer "Extra" "") :image (gnosis-select-image) - :tags (gnosis-tag-prompt))))) + :tags (gnosis-prompt-tags--split gnosis-previous-note-tags))))) ;;;###autoload (defun gnosis-add-note (type) @@ -849,9 +852,29 @@ Returns a list of unique tags." (defun gnosis-hint-prompt (previous-hint &optional prompt) (let* ((prompt (or prompt "Hint: ")) (hint (read-from-minibuffer prompt previous-hint))) - (setf gnosis-previous-hint hint) + (setf gnosis-previous-note-hint hint) hint)) +(defun gnosis-prompt-mcq-choices () + "Prompt user for mcq choices." + (let* ((input (split-string + (read-string-from-buffer "Options\nEach '-' corresponds to an option\n-Example Option 1\n-Example Option 2\nYou can add as many options as you want\nCorrect Option must be inside {}" "-\n-") + "-" 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 opiton"))) + (choices (mapcar (lambda (string) (replace-regexp-in-string "{\\|}" "" string)) input))) + (list choices (+ correct-choice-index 1)))) + +(defun gnosis-prompt-tags--split (&optional previous-note-tags) + "Prompt user for tags, split string by space. + +Return a list of tags, split by space. If PREVIOUS-NOTE-TAGS is +provided, use it as the default value." + (let* ((previous-note-tags (or nil previous-note-tags)) + (tags (split-string (read-from-minibuffer "Tags: " (mapconcat #'identity previous-note-tags " ")) " "))) + (setf gnosis-previous-note-tags tags) + tags)) + ;; Review ;;;;;;;;;; (defun gnosis-review-is-due-p (note-id) |