Merge branch 'version-0.1.3' to master0.1.3

- Add documentation
- Fix docstrings & types of custom vars

Improve algorithm implementation
- Adjust next ef and interval depending on consecutive & total
failures/successes
- Fix bugs for custom reviews where last-interv would be 0

1 files changed, 235 insertions, 0 deletions

diff --git a/doc/gnosis.org b/doc/gnosis.org
new file mode 100644
index 0000000..8d23a30
--- /dev/null
+++ b/doc/gnosis.org
@@ -0,0 +1,235 @@
+#+TITLE: Gnosis User Manual
+#+AUTHOR: Thanos Apollo
+#+email: [email protected]
+#+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{[email protected]}
+#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:[email protected],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: <https://thanosapollo.org/user-manual/gnosis>
++ Git repositories:
+  + main:               <https://git.thanosapollo.org/gnosis>
+  + sourcehut (mirror): <https://git.sr.ht/~thanosapollo/gnosis>
+
+#+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:
+
+   <https://github.com/radian-software/straight.el>
+  
+** 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
+
+* 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.
+
+
+
+Example:
+
+#+begin_src emacs-lisp
+  (setq gnosis-algorithm-ff 0.5)
+#+end_src
+
+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