summaryrefslogtreecommitdiff
path: root/doc/gnosis.org
diff options
context:
space:
mode:
authorThanos Apollo <[email protected]>2024-08-07 14:30:13 +0300
committerThanos Apollo <[email protected]>2024-08-07 14:45:39 +0300
commit741acfcb4c35359e8975f65ba1e16eb0d981c874 (patch)
treed7fca92d7eba5642d4e0b6265d8d79379a14a63c /doc/gnosis.org
parent6674a127682ccc1699df7ab864a7041b433aee75 (diff)
Update docs for version 0.4.0
Diffstat (limited to 'doc/gnosis.org')
-rw-r--r--doc/gnosis.org217
1 files changed, 98 insertions, 119 deletions
diff --git a/doc/gnosis.org b/doc/gnosis.org
index dc2e1f5..15afc52 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.3.1
-#+macro: release-date 2024-07-15
+#+macro: stable-version 0.4.0
+#+macro: release-date 2024-08-7
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
@@ -22,18 +22,10 @@
#+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. Notes are organized in a Question/Answer/Explanation format
-and reviewed at spaced intervals, determined by the success or failure
-to recall the answer.
-
-The goal of Gnosis is to enhance memory retention through active
-recall. To achieve optimal results, users review Gnosis notes by
-writing out the answers.
-
-Above all, Gnosis aspires to be a versatile instrument of learning.
+Gnosis is a customizable spaced repetition system designed to enhance
+memory retention through active recall. It allows users to set
+specific review intervals for note decks & tags, creating an optimal
+learning environment tailored to each specific topic.
#+texinfo: @noindent
This manual is written for Gnosis version {{{stable-version}}}, released on {{{release-date}}}.
@@ -46,24 +38,31 @@ This manual is written for Gnosis version {{{stable-version}}}, released on {{{r
* Introduction
-Before reading this manual, it's recommended you first try out =gnosis-demo=
-
-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 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 (γνῶσις) is a spaced repetition system that enhances memory
+retention through active recall. It employs a Q&A format, where each
+note consists of a question, answer, and explanation. Notes are
+reviewed at optimally spaced intervals based on the user's success or
+failure to recall the answer. Key benefits arise from writing out
+answers when reviewing notes, fostering deeper understanding
+and improved memory retention.
+
+Gnosis algorithm is highly adjustable, allowing users to set specific
+values not just for note decks but for tags as well. Gnosis'
+adjustability allows users to fine-tune settings not only for entire
+note collections but also for specific tagged topics, thereby creating
+a personalized learning environment for each topic. Read more on
[[Gnosis Algorithm]]
+Before continuing reading this manual, it's recommended you try out
+=gnosis-demo=.
+
* Adding notes
Creating notes for gnosis can be done interactively with:
=M-x gnosis-add-note=
+Or from within =gnosis-dashboard=
+
When it comes to adding images, you can select images that are inside
=gnosis-images-dir=. For adjusting image size, refer to [[#Customization][Customization]]
@@ -88,14 +87,23 @@ You can also format clozes like Anki if you so prefer; e.g ~{{c1::Cyproheptadine
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.
+ *UNIQUE* word, or a unique combination of words, in given note.
+
+ + If a cloze is repeated, such as in phrases with "acetyl" &
+ acetylcholine, include whitespace in the cloze to denote a single
+ word.
+ You can use the keyword =::= to indicate a hint.
You can remove the /guidance/ string by adjusting
=gnosis-cloze-guidance=.
-** MC-Cloze
+** MC-Cloze (Under development)
+
+MC-Cloze is disabled by default, to enable it add to your configuration:
+
+ =(add-to-list 'gnosis-note-types "MC-Cloze")=
+
A MC-Cloze (/Multiple Choice Cloze/) is a fill-in-the-blank note,
but unlike [[#Cloze][cloze note type]] the user is prompted to select an option
instead of typing an answer.
@@ -113,7 +121,7 @@ Example:
When customizing =gnosis-mc-cloze=separator= pay attention to not use
values that would mess up with regex functions.
-** MCQ (Multiple Choice Question)
+** MCQ
A MCQ note type, as the name suggests, is a multiple choice question.
@@ -179,92 +187,51 @@ 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 note has a gnosis score, which is a list of 3 values,
+(gnosis-plus gnosis-minus gnosis-synolon/total). Gnosis-synolon is
+what is used to determine the next interval upon a successful recall,
+gnosis-plus is added to gnosis-synolon upon a successful recall as
+well, gnosis-minus is subtracted from gnosis-synolon upon failing to
+recall a note's answer.
+
+Gnosis has 2 special events, one is ~anagnosis~ /ανάγνωση/ and ~lethe~ /λήθη/.
+** Anagnosis Event
+~Anagnosis~, which means comprehension & recognition of knowledge, is
+triggered when the consecutive successful or failed recalls are equal
+or greater to anagnosis value.
-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.
+When ~anagnosis~ is triggered by consecutive *successful* recalls,
+~epignosis~ value is added to gnosis-plus. /Epignosis means accuracy of knowledge/.
-You can customize deck specific algorithm values using =gnosis-dashboard=.
+When ~anagnosis~ is triggered by consecutive *failed* recalls,
+~agnoia~ value is added to gnosis-minus. /Agnoia means lack of knowledge/
-** Initial Interval
+You can set specific values for each deck and tag of the variables
+mentioned above by adjusting =gnosis-custom-values=.
+
+** Proto
The default initial interval is defined at
-=gnosis-algorithm-interval=, you can define a custom initial interval
+=gnosis-algorithm-proto=, 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.
+=gnosis-algorithm-interval= is a list of numbers, representing the
+first initial intervals for successful reviews. There is no limit on
+the length of the list.
Example:
#+begin_src emacs-lisp
- (setq gnosis-algorithm-interval '(0 1))
-#+end_src
-
-Using the above example, after first successfully reviewing a note,
-you will see it again in the next review session, if you successfully
-review said note again, the next review will be tomorrow.
-
-Upon failing to review a note without completing 2 successful reviews,
-you will have to review it again on the same day.
-
-** Easiness Factor
-
-The =gnosis-algorithm-ef= is a list that consists of three items:
-
-1. Easiness factor increase value: Added to the easiness factor upon a
- successful review.
-
-2. Easiness factor decrease value: Subtracted from the total easiness
- factor upon a failed review.
-
-3. Total Easiness factor: Used to calculate the next interval.
-
-
-How this is used:
-
-Multiplies the last interval by the easiness factor after a successful
-review.
-
-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:
-
-#+begin_src emacs-lisp
- (setq gnosis-algorithm-ef '(0.30 0.25 1.3))
+ (setq gnosis-algorithm-interval '(0 1 2 30))
#+end_src
-** Forgetting Factor
-
-=gnosis-algorithm-ff= is a floating number below 1.
-
-Used to determine the next interval after an unsuccessful review.
-
-Multiplied with the last interval to calculate the next interval. For
-example, if =gnosis-algorithm-ff= is set to 0.5 and the last interval
-was 6 days, the next interval will be 6 * 0.5 = 3 days.
-
+Upon each successful note review, the algorithm will increment to the
+next interval value: 0 days (0), 1 day later (1), 2 days later
+(2), and 30 days later.
-Example configuration:
+Upon failing to review a note without completing it's proto successful reviews,
+it's next review date will be on the same date.
-#+begin_src emacs-lisp
- (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:
@@ -300,14 +267,27 @@ To automatically push changes after a review session, add this to your configura
(gnosis-vc-pull) ;; Run vc-pull for gnosis on startup
#+end_src
-* Extending Gnosis
-To make development and customization easier, gnosis comes with
-=gnosis-test= module, that should be used to create a custom database for
-testing.
+* Configuring Note Types
+** Adjust Current Types Entries
+Each gnosis note type has an /interactive/ function, named
+=gnosis-add-note-TYPE=. You can set default values for each entry by
+hard coding specific values to their keywords.
-To exit the testing environment, rerun =M-x gnosis-test-start= and
-then enter =n= (no) at the prompt "Start development env?"
+For example:
+
+#+begin_src emacs-lisp
+(defun gnosis-add-note-basic (deck)
+ (gnosis-add-note--basic :deck deck
+ :question (gnosis-read-string-from-buffer "Question: " "")
+ :answer (read-string "Answer: ")
+ :hint (gnosis-hint-prompt gnosis-previous-note-hint)
+ :extra ""
+ :images nil
+ :tags (gnosis-prompt-tags--split gnosis-previous-note-tags)))
+#+end_src
+By evaluating the above code snippet, you won't be prompted to enter
+anything for ~extra~ & ~images~.
** Creating Custom Note Types
Creating custom note types for gnosis is a fairly simple thing to do
@@ -315,23 +295,22 @@ 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-note-type")
+ (add-to-list 'gnosis-note-types "NEW-TYPE")
#+end_src
++ Create an interactive function
-+ Create 2 functions; =gnosis-add-note-TYPE= & =gnosis-add-note--TYPE=
-
-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.
+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. You can use one of the =current gnosis-add-note--TYPE=
+functions or create one of your own.
Refer to =gnosis-add-note-basic= & =gnosis-add-note--basic= for a simple
-example of how this is done.
+example of how this is done, as well as =gnosis-add-note-double=.
-+ Create =gnosis-review-TYPE=
-
-This function should handle the review process, displaying it's
-contents and updating the database depending on the result of the
-review (fail/pass). Refer to =gnosis-review-basic= for an example of how
-this should be done.
+** Development
+To make development and customization easier, gnosis comes with
+=gnosis-test= module, that should be used to create a custom database for
+testing.
-+ Optionally, you might want to create your own custom =gnosis-display= functions
+To exit the testing environment, rerun =M-x gnosis-test-start= and
+then enter =n= (no) at the prompt "Start development env?"