[doc] Update documentation for version 0.3.0

3 files changed, 153 insertions, 44 deletions

diff --git a/doc/gnosis.info b/doc/gnosis.info
index 885f23d..f9296f3 100644
--- a/doc/gnosis.info
+++ b/doc/gnosis.info
@@ -1,4 +1,5 @@
-This is gnosis.info, produced by makeinfo version 7.1 from gnosis.texi.
+This is gnosis.info, produced by .texi2any-real version 7.1 from
+gnosis.texi.
 
 INFO-DIR-SECTION Emacs misc features
 START-INFO-DIR-ENTRY
@@ -13,9 +14,14 @@ Gnosis User Manual
 
 Gnosis (γνῶσις), pronounced "noh-sis", _meaning knowledge in Greek_, is
 a spaced repetition system implementation for note taking and self
-testing.
+testing.  The objective of gnosis is to maximize memory retention by
+implementing reviewing of information at increasing intervals.
 
-This manual is written for Gnosis version 0.2.0, released on 2023-03-08.
+   The intervals grow longer as you become more familiar with the
+information, which reinforces long-term retention and reduces the risk
+of forgetting
+
+This manual is written for Gnosis version 0.3.0, released on 2024-06-28.
 
    • Official manual: <https://thanosapollo.org/user-manual/gnosis>
    • Git repositories:
@@ -37,6 +43,7 @@ This manual is written for Gnosis version 0.2.0, released on 2023-03-08.
 Note Types
 
 * Cloze::
+* MC-Cloze::
 * MCQ (Multiple Choice Question)::
 * Basic Type::
 * Double::
@@ -64,7 +71,10 @@ File: gnosis.info,  Node: Introduction,  Next: Adding notes,  Prev: Top,  Up: To
 1 Introduction
 **************
 
-Gnosis, is a spaced repetition system for note taking & self testing,
+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.
@@ -98,13 +108,14 @@ File: gnosis.info,  Node: Note Types,  Next: Customization,  Prev: Adding notes,
 * Menu:
 
 * Cloze::
+* MC-Cloze::
 * MCQ (Multiple Choice Question)::
 * Basic Type::
 * Double::
 * y-or-n::
 
 
-File: gnosis.info,  Node: Cloze,  Next: MCQ (Multiple Choice Question),  Up: Note Types
+File: gnosis.info,  Node: Cloze,  Next: MC-Cloze,  Up: Note Types
 
 3.1 Cloze
 =========
@@ -131,9 +142,31 @@ selecting ‘Cloze’, the question should be formatted like this:
 ‘gnosis-cloze-guidance’.
 
 
-File: gnosis.info,  Node: MCQ (Multiple Choice Question),  Next: Basic Type,  Prev: Cloze,  Up: Note Types
+File: gnosis.info,  Node: MC-Cloze,  Next: MCQ (Multiple Choice Question),  Prev: Cloze,  Up: Note Types
+
+3.2 MC-Cloze
+============
 
-3.2 MCQ (Multiple Choice Question)
+A MC-Cloze (_Multiple Choice Cloze_) is a fill-in-the-blank note, but
+unlike *note cloze note type: Cloze. the user is prompted to select an
+option instead of typing an answer.
+
+   You can create multiple notes from one input, but each note can only
+have *one* cloze.  The first option will always be the right answer
+(will be randomized in the database), separated by the rest of the
+answer by ‘gnosis-mc-cloze-separator’ (default value is "&&"), and a
+note will be generated from each cloze.
+
+   Example:
+     The greatest text editor is Emacs&&Vim&&Helix
+
+   When customizing ‘gnosis-mc-cloze=separator’ pay attention to not use
+values that would mess up with regex functions.
+
+
+File: gnosis.info,  Node: MCQ (Multiple Choice Question),  Next: Basic Type,  Prev: MC-Cloze,  Up: Note Types
+
+3.3 MCQ (Multiple Choice Question)
 ==================================
 
 A MCQ note type, as the name suggests, is a multiple choice question.
@@ -148,7 +181,7 @@ A MCQ note type, as the name suggests, is a multiple choice question.
 
 File: gnosis.info,  Node: Basic Type,  Next: Double,  Prev: MCQ (Multiple Choice Question),  Up: Note Types
 
-3.3 Basic Type
+3.4 Basic Type
 ==============
 
 Basic note type is a simple question/answer note, where the user first
@@ -158,7 +191,7 @@ input the answer.
 
 File: gnosis.info,  Node: Double,  Next: y-or-n,  Prev: Basic Type,  Up: Note Types
 
-3.4 Double
+3.5 Double
 ==========
 
 Double note type, is essentially a note that generates 2 basic notes.
@@ -169,7 +202,7 @@ The second one reverses question/answer.
 
 File: gnosis.info,  Node: y-or-n,  Prev: Double,  Up: Note Types
 
-3.5 y-or-n
+3.6 y-or-n
 ==========
 
 y-or-n (yes or no) note type, user is presented with a question and
@@ -272,6 +305,9 @@ first two initial intervals for successful reviews.
 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.
+
 
 File: gnosis.info,  Node: Easiness Factor,  Next: Forgetting Factor,  Prev: Initial Interval,  Up: Gnosis Algorithm
 
@@ -349,7 +385,7 @@ synchronization across devices.
 
      cd ~/.emacs.d/gnosis # default location for gnosis
      git init # After completing your first review session, a git repo should have been initialized automatically.
-     git remote add <remote_name> <remote_url>
+     git remote add origin <remote_url>
      git push --set-upstream origin master
 
    You can interactively use ‘gnosis-vc-push’ & ‘gnosis-vc-pull’.  As
@@ -415,26 +451,27 @@ should be done.
 
 
 Tag Table:
-Node: Top244
-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
+Node: Top250
+Node: Introduction1503
+Node: Adding notes2230
+Node: Note Types2599
+Node: Cloze2824
+Node: MC-Cloze3720
+Node: MCQ (Multiple Choice Question)4544
+Node: Basic Type5043
+Node: Double5346
+Node: y-or-n5612
+Node: Customization6014
+Node: Image size6199
+Node: Typos | String Comparison6485
+Node: Gnosis Algorithm7260
+Node: Initial Interval8296
+Node: Easiness Factor9086
+Node: Forgetting Factor10034
+Node: Editing notes10642
+Node: Sync between devices11034
+Node: Extending Gnosis12055
+Node: Creating Custom Note Types12510
 
 End Tag Table
 
diff --git a/doc/gnosis.org b/doc/gnosis.org
index 9ff58e8..0e0ccde 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.2.0
-#+macro: release-date 2023-03-08
+#+macro: stable-version 0.3.0
+#+macro: release-date 2024-06-28
 #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
 #+macro: space @@texinfo:@: @@
 #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
@@ -22,9 +22,14 @@
 #+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.
+Gnosis (γνῶσις), pronounced "noh-sis", /meaning knowledge in Greek/,
+is a spaced repetition system implementation for note taking and self
+testing.  The objective of gnosis is to maximize memory retention by
+implementing reviewing  of information at increasing intervals.
+
+The intervals grow longer as you become more familiar with the
+information, which reinforces long-term retention and reduces the risk
+of forgetting
 
 #+texinfo: @noindent
 This manual is written for Gnosis version {{{stable-version}}}, released on {{{release-date}}}.
@@ -36,6 +41,9 @@ This manual is written for Gnosis version {{{stable-version}}}, released on {{{r
 #+texinfo: @insertcopying
 
 * 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
@@ -53,11 +61,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 [[Customization]]
+=gnosis-images-dir=.  For adjusting image size, refer to [[#Customization][Customization]]
 
 * Note Types
 ** Cloze
-
+:PROPERTIES:
+:CUSTOM_ID: Cloze
+:END:
 A cloze note type is a format where you create sentences or paragraphs
 with "missing" words.  A fill-in-the-blanks question.  
 
@@ -79,6 +89,24 @@ You can also format clozes like Anki if you prefer; e.g ~{{c1::Cyproheptadine}}~
 You can remove the /guidance/ string by adjusting
 =gnosis-cloze-guidance=.
 
+** 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.
+
+You can create multiple notes from one input, but each note can only
+have *one* cloze. The first option will always be the right answer
+(will be randomized in the database), separated by the rest of the
+answer by =gnosis-mc-cloze-separator= (default value is "&&"), and a
+note will be generated from each cloze.
+
+Example:
+#+BEGIN_QUOTE
+    The greatest text editor is Emacs&&Vim&&Helix
+#+END_QUOTE
+
+When customizing =gnosis-mc-cloze=separator= pay attention to not use
+values that would mess up with regex functions.
 ** MCQ (Multiple Choice Question)
 
 A MCQ note type, as the name suggests, is a multiple choice question.
@@ -111,7 +139,13 @@ ANSWER must be either 121 (~y~) or 110 (~n~), as those correspond to the
 character values used to represent them.
 
 * Customization
+:PROPERTIES:
+:CUSTOM_ID: Customization
+:END:
 ** Image size
+:PROPERTIES:
+:CUSTOM_ID: image-size
+:END:
 Adjust image size using =gnosis-image-height= & =gnosis-image-width=
 
 Example:
@@ -176,6 +210,9 @@ 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:
@@ -240,7 +277,7 @@ Example:
 #+begin_src bash
  cd ~/.emacs.d/gnosis # default location for gnosis
  git init # After completing your first review session, a git repo should have been initialized automatically.
- git remote add <remote_name> <remote_url>
+ git remote add origin <remote_url>
  git push --set-upstream origin master
 #+end_src
 
@@ -257,6 +294,7 @@ To automatically push changes after a review session, add this to your configura
 (setf gnosis-vc-auto-push t)
 (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
diff --git a/doc/gnosis.texi b/doc/gnosis.texi
index 7f98492..f213740 100644
--- a/doc/gnosis.texi
+++ b/doc/gnosis.texi
@@ -25,12 +25,17 @@
 @node Top
 @top Gnosis User Manual
 
-Gnosis (γνῶσις), pronounced ``noh-sis'', @emph{meaning knowledge in Greek}, is
-a spaced repetition system implementation for note taking and self
-testing.
+Gnosis (γνῶσις), pronounced ``noh-sis'', @emph{meaning knowledge in Greek},
+is a spaced repetition system implementation for note taking and self
+testing.  The objective of gnosis is to maximize memory retention by
+implementing reviewing  of information at increasing intervals.
+
+The intervals grow longer as you become more familiar with the
+information, which reinforces long-term retention and reduces the risk
+of forgetting
 
 @noindent
-This manual is written for Gnosis version 0.2.0, released on 2023-03-08.
+This manual is written for Gnosis version 0.3.0, released on 2024-06-28.
 
 @itemize
 @item
@@ -62,6 +67,7 @@ Git repositories:
 Note Types
 
 * Cloze::
+* MC-Cloze::
 * MCQ (Multiple Choice Question)::
 * Basic Type::
 * Double::
@@ -88,6 +94,8 @@ Extending Gnosis
 @node Introduction
 @chapter Introduction
 
+Before reading this manual, it's recommended you first try out @samp{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
@@ -114,6 +122,7 @@ When it comes to adding images, you can select images that are inside
 
 @menu
 * Cloze::
+* MC-Cloze::
 * MCQ (Multiple Choice Question)::
 * Basic Type::
 * Double::
@@ -149,6 +158,28 @@ Each `cX` tag can have multiple clozes, but each cloze must be a
 You can remove the @emph{guidance} string by adjusting
 @samp{gnosis-cloze-guidance}.
 
+@node MC-Cloze
+@section MC-Cloze
+
+A MC-Cloze (@emph{Multiple Choice Cloze}) is a fill-in-the-blank note,
+but unlike @ref{Cloze, , cloze note type} the user is prompted to select an option
+instead of typing an answer.
+
+You can create multiple notes from one input, but each note can only
+have @strong{one} cloze. The first option will always be the right answer
+(will be randomized in the database), separated by the rest of the
+answer by @samp{gnosis-mc-cloze-separator} (default value is ``&&''), and a
+note will be generated from each cloze.
+
+Example:
+@quotation
+The greatest text editor is Emacs&&Vim&&Helix
+
+@end quotation
+
+When customizing @samp{gnosis-mc-cloze=separator} pay attention to not use
+values that would mess up with regex functions.
+
 @node MCQ (Multiple Choice Question)
 @section MCQ (Multiple Choice Question)
 
@@ -271,6 +302,9 @@ 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.
+
 @node Easiness Factor
 @section Easiness Factor
 
@@ -354,7 +388,7 @@ Example:
 @example
 cd ~/.emacs.d/gnosis # default location for gnosis
 git init # After completing your first review session, a git repo should have been initialized automatically.
-git remote add <remote_name> <remote_url>
+git remote add origin <remote_url>
 git push --set-upstream origin master
 @end example