From 49d0ae892fd3f96e4c346c9660f370554b3dcd3f Mon Sep 17 00:00:00 2001 From: Thanos Apollo Date: Thu, 18 Jan 2024 02:45:34 +0200 Subject: Add documentation Documentation is generated from gnosis.org --- doc/gnosis.org | 232 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 doc/gnosis.org (limited to 'doc/gnosis.org') diff --git a/doc/gnosis.org b/doc/gnosis.org new file mode 100644 index 0000000..cccd625 --- /dev/null +++ b/doc/gnosis.org @@ -0,0 +1,232 @@ +#+TITLE: Gnosis User Manual +#+AUTHOR: Thanos Apollo +#+email: public@thanosapollo.org +#+language: en +#+options: ':t toc:nil author:t email:t num:t +#+startup: content +#+macro: stable-version 0.1.3 +#+macro: release-date 2023-01-18 +#+macro: development-version 0.1.4-dev +#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ +#+macro: space @@texinfo:@: @@ +#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ +#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ +#+macro: space @@texinfo:@: @@ +#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ +#+texinfo_filename: gnosis.info +#+texinfo_dir_category: Emacs misc features +#+texinfo_dir_title: Gnosis (γνῶσις): (gnosis) +#+texinfo_dir_desc: Spaced Repetition System For Note Taking And Self-Testing +#+texinfo_header: @set MAINTAINERSITE @uref{https://thanosapollo.org,maintainer webpage} +#+texinfo_header: @set MAINTAINER Thanos Apollo +#+texinfo_header: @set MAINTAINEREMAIL @email{public@thanosapollo.org} +#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:public@thanosapollo.org,contact the maintainer} + + +Gnosis (γνῶσις), pronounced "noh-sis", /meaning knowledge in Greek/, is +a spaced repetition system implementation for note taking and self +testing. + +#+texinfo: @noindent +This manual is written for Gnosis version {{{stable-version}}}, released on {{{release-date}}}. + ++ Official manual: ++ Git repositories: + + main: + + sourcehut (mirror): + +#+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 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 not currently available in any ELPA, the recommended way to +install gnosis is via straight.el: + + + +** 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: + +#+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 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 + +* Adding notes +Creating notes for gnosis can be done interactively with: + =M-x gnosis-add-note= + + +Advanced/Power users may prefer to use =gnosis-add-note--TYPE= + +Example: + +#+begin_src emacs-lisp + (gnosis-add-note--basic :deck "DECK-NAME" + :question "Your Question" + :answer "Answer" + :hint "hint" + :extra "Explanation" + :image "Image displayed before user-input" ;; Optional + :second-image "Image displayed after user-input" ;; Optional + :tags '("tag1" "tag2")) +#+end_src + +By default, the value of image and second image is nil. Their value +must a string, the path of an image, from inside ~gnosis-images-dir~. + +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. + +Every note type has these values in common: + + + ~extra~ string value, extra information/explanation displayed after user-input + + ~image~ Image displayed /before/ user input + + ~second-image~ Image displayed /after/ user input + +The following sections will cover the important differences you have +to know when creating notes. + +* 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. + +You can create a cloze note type using =M-x gnosis-add-note= and +selecting ~Cloze~, the question should be formatted like this: + +#+BEGIN_QUOTE +{c1:Cyproheptadine} is a(n) {c2:5-HT2} receptor antagonist used to treat {c2:serotonin syndrome} +#+END_QUOTE + +You can also format clozes like Anki if you prefer; e.g ~{{c1::Cyproheptadine}}~ + ++ For each `cX`-tag there will be created a cloze type note, the above + 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. + +** Basic Type + +Basic note type is a simple question/answer note, where the user first +sees a "main" part, which is usually a question, and he is prompted to +input the answer. + +** 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. + +** 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". + +When using the hidden function =gnosis-add-note--y-or-n=, note that the +ANSWER must be either 121 (~y~) or 110 (~n~), as those correspond to the +character values used to represent them. + +* Customization +** Gnosis Algorithm Initial Interval + +=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)) +#+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. + +** Gnosis Algorithm Easiness Factor + +=gnosis-algorithm-ef= is a list that consists of 3 items. + +The first item is the increase factor, used to increase the easiness +factor upon successful review. + +Second item refers to the decrease factor, used to +decrease the easiness factor upon an unsuccessful review. + +The third item is the initial total easiness factor, used to calculate +the next interval. + +The basic's of how this is used is that it's being multiplied with the +last interval upon a successful review, e.g if you last reviewed a +note 6 days ago, and the easiness factor of this note is 2.0, your +next interval would be 6 * 2.0 & the total easiness factor would be +2.0 + increase-factor as well. + +Example: + +#+begin_src emacs-lisp + (setq gnosis-algorithm-ef '(0.3 0.3 1.3)) +#+end_src + +** Gnosis Algorithm Forgetting Factor + +=gnosis-algorithm-ff= is a floating number below 1. + +It's used to calculate the next interval upon an unsuccessful review, +by being multiplied with last interval, if for a note with a value of +last-interval of 6 days and a ff of 0.5, upon an unsuccessful review +the next interval will be 6 * 0.5 + +For example: + +#+begin_src emacs-lisp + (setq gnosis-algorithm-ff 0.5) +#+end_src -- cgit v1.2.3