summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/gnosis.info221
-rw-r--r--doc/gnosis.org124
-rw-r--r--doc/gnosis.texi151
-rw-r--r--gnosis.el41
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
diff --git a/gnosis.el b/gnosis.el
index b2c2e40..4a89c2e 100644
--- a/gnosis.el
+++ b/gnosis.el
@@ -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")))