doc: Update cloze section

3 files changed, 71 insertions, 55 deletions

diff --git a/doc/gnosis.info b/doc/gnosis.info
index f9296f3..6bab4f5 100644
--- a/doc/gnosis.info
+++ b/doc/gnosis.info
@@ -14,14 +14,17 @@ Gnosis User Manual
 
 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.
+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 intervals grow longer as you become more familiar with the
-information, which reinforces long-term retention and reduces the risk
-of forgetting
+   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.
 
-This manual is written for Gnosis version 0.3.0, released on 2024-06-28.
+   Above all, Gnosis aspires to be a versatile instrument of learning.
+
+This manual is written for Gnosis version 0.3.1, released on 2024-07-15.
 
    • Official manual: <https://thanosapollo.org/user-manual/gnosis>
    • Git repositories:
@@ -126,18 +129,20 @@ 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:
 
-     {c1:Cyproheptadine} is a(n) {c2:5-HT2} receptor antagonist used to
-     treat {c2:serotonin syndrome}
+     {c1:Cyproheptadine::drug name} is a(n) {c2:5-HT2} receptor
+     antagonist used to treat {c2:serotonin syndrome}
 
-   You can also format clozes like Anki if you prefer; e.g
-‘{{c1::Cyproheptadine}}’
+   You can also format clozes like Anki if you so prefer; e.g
+‘{{c1::Cyproheptadine::drug name}}’
 
-   • For each 'cX'-tag there will be created a cloze type note, the
-     above example creates 2 cloze type notes.
+   • 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
+   • 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 use the keyword ‘::’ to indicate a hint.
+
    You can remove the _guidance_ string by adjusting
 ‘gnosis-cloze-guidance’.
 
@@ -452,26 +457,26 @@ should be done.
 
 Tag Table:
 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
+Node: Introduction1614
+Node: Adding notes2341
+Node: Note Types2710
+Node: Cloze2935
+Node: MC-Cloze3913
+Node: MCQ (Multiple Choice Question)4737
+Node: Basic Type5236
+Node: Double5539
+Node: y-or-n5805
+Node: Customization6207
+Node: Image size6392
+Node: Typos | String Comparison6678
+Node: Gnosis Algorithm7453
+Node: Initial Interval8489
+Node: Easiness Factor9279
+Node: Forgetting Factor10227
+Node: Editing notes10835
+Node: Sync between devices11227
+Node: Extending Gnosis12248
+Node: Creating Custom Note Types12703
 
 End Tag Table
 
diff --git a/doc/gnosis.org b/doc/gnosis.org
index 0e0ccde..dc2e1f5 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.0
-#+macro: release-date 2024-06-28
+#+macro: stable-version 0.3.1
+#+macro: release-date 2024-07-15
 #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
 #+macro: space @@texinfo:@: @@
 #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
@@ -22,14 +22,18 @@
 #+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.  The objective of gnosis is to maximize memory retention by
-implementing reviewing  of information at increasing intervals.
+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.
 
-The intervals grow longer as you become more familiar with the
-information, which reinforces long-term retention and reduces the risk
-of forgetting
+Above all, Gnosis aspires to be a versatile instrument of learning.
 
 #+texinfo: @noindent
 This manual is written for Gnosis version {{{stable-version}}}, released on {{{release-date}}}.
@@ -75,17 +79,19 @@ 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}
+{c1:Cyproheptadine::drug name} 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}}~
+You can also format clozes like Anki if you so prefer; e.g ~{{c1::Cyproheptadine::drug name}}~
 
-+ For each `cX`-tag there will be created a cloze type note, the above
++ 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
++ 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 use the keyword =::= to indicate a hint.
+
 You can remove the /guidance/ string by adjusting
 =gnosis-cloze-guidance=.
 
@@ -117,7 +123,6 @@ The stem field (question) is separated by the options (choices) via
 You can remove the /guidance/ string by adjusting
 =gnosis-mcq-guidance=.
 
-
 ** Basic Type
 
 Basic note type is a simple question/answer note, where the user first
diff --git a/doc/gnosis.texi b/doc/gnosis.texi
index f213740..b48163b 100644
--- a/doc/gnosis.texi
+++ b/doc/gnosis.texi
@@ -27,15 +27,18 @@
 
 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.
+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 intervals grow longer as you become more familiar with the
-information, which reinforces long-term retention and reduces the risk
-of forgetting
+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.
 
 @noindent
-This manual is written for Gnosis version 0.3.0, released on 2024-06-28.
+This manual is written for Gnosis version 0.3.1, released on 2024-07-15.
 
 @itemize
 @item
@@ -139,20 +142,23 @@ 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:
 
 @quotation
-@{c1:Cyproheptadine@} is a(n) @{c2:5-HT2@} receptor antagonist used to treat @{c2:serotonin syndrome@}
+@{c1:Cyproheptadine::drug name@} is a(n) @{c2:5-HT2@} receptor antagonist used to treat @{c2:serotonin syndrome@}
 
 @end quotation
 
-You can also format clozes like Anki if you prefer; e.g @code{@{@{c1::Cyproheptadine@}@}}
+You can also format clozes like Anki if you so prefer; e.g @code{@{@{c1::Cyproheptadine::drug name@}@}}
 
 @itemize
 @item
-For each `cX`-tag there will be created a cloze type note, the above
+For each cX-tag there will be created a cloze type note, the above
 example creates 2 cloze type notes.
 
 @item
-Each `cX` tag can have multiple clozes, but each cloze must be a
+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.
+
+@item
+You can use the keyword @samp{::} to indicate a hint.
 @end itemize
 
 You can remove the @emph{guidance} string by adjusting