From d09057b49e1fdf3d993e054c688baa3dc2d46efc Mon Sep 17 00:00:00 2001 From: Thanos Apollo Date: Fri, 8 Mar 2024 09:24:03 +0200 Subject: Update doc & fix typos --- doc/gnosis.texi | 151 +++++++++++++++++++------------------------------------- 1 file changed, 50 insertions(+), 101 deletions(-) (limited to 'doc/gnosis.texi') 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 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 -- cgit v1.2.3