From 76a1d7b0589d2ea09aa0cb3750b9498ae6944e8a Mon Sep 17 00:00:00 2001 From: Thanos Apollo Date: Fri, 19 Jan 2024 16:42:16 +0200 Subject: Update documentation .texi & info files --- doc/gnosis.info | 125 +++++++++++++++++++++++++++++++++++++++++--------------- doc/gnosis.texi | 95 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 179 insertions(+), 41 deletions(-) diff --git a/doc/gnosis.info b/doc/gnosis.info index fe0338a..ddae27d 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.3, released on 2023-01-18. +This manual is written for Gnosis version 0.1.4, released on 2023-01-19. • Official manual: • Git repositories: @@ -28,7 +28,7 @@ This manual is written for Gnosis version 0.1.3, released on 2023-01-18. * Installation:: * Adding notes:: * Note Types:: -* Customization:: +* Customization & Development:: -- The Detailed Node Listing -- @@ -45,7 +45,12 @@ Note Types * MCQ (Multiple Choice Question):: * y-or-n:: -Customization +Customization & Development + +* Creating Custom Note Types:: +* Customizing Gnosis Algorithm:: + +Customizing Gnosis Algorithm * Gnosis Algorithm Initial Interval:: * Gnosis Algorithm Easiness Factor:: @@ -156,10 +161,10 @@ all the logic. • ‘second-image’ Image displayed _after_ user input The following sections will cover the important differences you have -to know when creating notes. +to know when creating new notes.  -File: gnosis.info, Node: Note Types, Next: Customization, Prev: Adding notes, Up: Top +File: gnosis.info, Node: Note Types, Next: Customization & Development, Prev: Adding notes, Up: Top 4 Note Types ************ @@ -249,10 +254,64 @@ the ANSWER must be either 121 (‘y’) or 110 (‘n’), as those correspond to the character values used to represent them.  -File: gnosis.info, Node: Customization, Prev: Note Types, Up: Top +File: gnosis.info, Node: Customization & Development, Prev: Note Types, Up: Top + +5 Customization & Development +***************************** + +To make development and customization easier, gnosis comes with +‘gnosis-dev’ module, that should be used to create a custom database for +testing. + + To use ‘gnosis-dev’, first you have to ‘(require 'gnosis-dev)’ & run +‘M-x gnosis-dev-test’. This will create a new directory 'testing' with +a new database. + + To exit the testing environment, rerun ‘M-x gnosis-dev-test’ and then +enter ‘n’ (no) at the prompt "Start development env?" + +* Menu: + +* Creating Custom Note Types:: +* Customizing Gnosis Algorithm:: + + +File: gnosis.info, Node: Creating Custom Note Types, Next: Customizing Gnosis Algorithm, Up: Customization & Development + +5.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) + + • 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. + + Refer to ‘gnosis-add-note-basic’ & ‘gnosis-add-note--basic’ for a +simple example of how this is done. + + • 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. + + • Optionally, you might want to create your own custom + ‘gnosis-display’ functions + + +File: gnosis.info, Node: Customizing Gnosis Algorithm, Prev: Creating Custom Note Types, Up: Customization & Development -5 Customization -*************** +5.2 Customizing Gnosis Algorithm +================================ * Menu: @@ -261,10 +320,10 @@ File: gnosis.info, Node: Customization, Prev: Note Types, Up: Top * Gnosis Algorithm Forgetting Factor::  -File: gnosis.info, Node: Gnosis Algorithm Initial Interval, Next: Gnosis Algorithm Easiness Factor, Up: Customization +File: gnosis.info, Node: Gnosis Algorithm Initial Interval, Next: Gnosis Algorithm Easiness Factor, Up: Customizing Gnosis Algorithm -5.1 Gnosis Algorithm Initial Interval -===================================== +5.2.1 Gnosis Algorithm Initial Interval +--------------------------------------- ‘gnosis-algorithm-interval’ is a list of 2 numbers, representing the first two initial intervals for successful reviews. @@ -278,10 +337,10 @@ you will see it again tomorrow, if you successfully review said note again, the next review will be after 3 days.  -File: gnosis.info, Node: Gnosis Algorithm Easiness Factor, Next: Gnosis Algorithm Forgetting Factor, Prev: Gnosis Algorithm Initial Interval, Up: Customization +File: gnosis.info, Node: Gnosis Algorithm Easiness Factor, Next: Gnosis Algorithm Forgetting Factor, Prev: Gnosis Algorithm Initial Interval, Up: Customizing Gnosis Algorithm -5.2 Gnosis Algorithm Easiness Factor -==================================== +5.2.2 Gnosis Algorithm Easiness Factor +-------------------------------------- ‘gnosis-algorithm-ef’ is a list that consists of 3 items. @@ -305,10 +364,10 @@ increase-factor as well. (setq gnosis-algorithm-ef '(0.3 0.3 1.3))  -File: gnosis.info, Node: Gnosis Algorithm Forgetting Factor, Prev: Gnosis Algorithm Easiness Factor, Up: Customization +File: gnosis.info, Node: Gnosis Algorithm Forgetting Factor, Prev: Gnosis Algorithm Easiness Factor, Up: Customizing Gnosis Algorithm -5.3 Gnosis Algorithm Forgetting Factor -====================================== +5.2.3 Gnosis Algorithm Forgetting Factor +---------------------------------------- ‘gnosis-algorithm-ff’ is a floating number below 1. @@ -326,21 +385,23 @@ upon an unsuccessful review the next interval will be 6 * 0.5  Tag Table: Node: Top246 -Node: Introduction1249 -Node: Installation1729 -Node: Using straightel2098 -Node: Installing manually from source2614 -Node: Adding notes3303 -Node: Note Types4729 -Node: Cloze4941 -Node: Basic Type5914 -Node: Double6192 -Node: MCQ (Multiple Choice Question)6538 -Node: y-or-n6947 -Node: Customization7373 -Node: Gnosis Algorithm Initial Interval7602 -Node: Gnosis Algorithm Easiness Factor8174 -Node: Gnosis Algorithm Forgetting Factor9159 +Node: Introduction1372 +Node: Installation1852 +Node: Using straightel2221 +Node: Installing manually from source2737 +Node: Adding notes3426 +Node: Note Types4856 +Node: Cloze5082 +Node: Basic Type6055 +Node: Double6333 +Node: MCQ (Multiple Choice Question)6679 +Node: y-or-n7088 +Node: Customization & Development7514 +Node: Creating Custom Note Types8195 +Node: Customizing Gnosis Algorithm9299 +Node: Gnosis Algorithm Initial Interval9617 +Node: Gnosis Algorithm Easiness Factor10208 +Node: Gnosis Algorithm Forgetting Factor11212  End Tag Table diff --git a/doc/gnosis.texi b/doc/gnosis.texi index 58c7f4e..9054e3f 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.3, released on 2023-01-18. +This manual is written for Gnosis version 0.1.4, released on 2023-01-19. @itemize @item @@ -54,7 +54,7 @@ sourcehut (mirror): @uref{https://git.sr.ht/~thanosapollo/gnosis} * Installation:: * Adding notes:: * Note Types:: -* Customization:: +* Customization & Development:: @detailmenu --- The Detailed Node Listing --- @@ -72,7 +72,12 @@ Note Types * MCQ (Multiple Choice Question):: * y-or-n:: -Customization +Customization & Development + +* Creating Custom Note Types:: +* Customizing Gnosis Algorithm:: + +Customizing Gnosis Algorithm * Gnosis Algorithm Initial Interval:: * Gnosis Algorithm Easiness Factor:: @@ -187,11 +192,19 @@ Every note type has these values in common: @end itemize The following sections will cover the important differences you have -to know when creating notes. +to know when creating new notes. @node Note Types @chapter Note Types +@menu +* Cloze:: +* Basic Type:: +* Double:: +* MCQ (Multiple Choice Question):: +* y-or-n:: +@end menu + @node Cloze @section Cloze @@ -257,11 +270,75 @@ When using the hidden function @samp{gnosis-add-note--y-or-n}, note that the ANSWER must be either 121 (@code{y}) or 110 (@code{n}), as those correspond to the character values used to represent them. -@node Customization -@chapter Customization +@node Customization & Development +@chapter Customization & Development + +To make development and customization easier, gnosis comes with +@samp{gnosis-dev} module, that should be used to create a custom database for +testing. + +To use @samp{gnosis-dev}, first you have to @samp{(require 'gnosis-dev)} & run @samp{M-x +gnosis-dev-test}. This will create a new directory 'testing' with a new +database. + +To exit the testing environment, rerun @samp{M-x gnosis-dev-test} and then +enter @samp{n} (no) at the prompt ``Start development env?'' + +@menu +* Creating Custom Note Types:: +* Customizing Gnosis Algorithm:: +@end menu + +@node Creating Custom Note Types +@section Creating Custom Note Types + +Creating custom note types for gnosis is a fairly simple thing to do + +@itemize +@item +First add your NEW-TYPE to @samp{gnosis-note-types} + +@lisp +(add-to-list 'gnosis-note-types 'new-type) +@end lisp + +@item +Create 2 functions; @samp{gnosis-add-note-TYPE} & @samp{gnosis-add-note--TYPE} +@end itemize + +Each note type has a @samp{gnosis-add-note-TYPE} that is used +interactively & a ``hidden function'' @samp{gnosis-add-note--TYPE} that handles +all the logic. + +Refer to @samp{gnosis-add-note-basic} & @samp{gnosis-add-note--basic} for a simple +example of how this is done. + +@itemize +@item +Create @samp{gnosis-review-TYPE} +@end itemize + +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 @samp{gnosis-review-basic} for an example of how +this should be done. + +@itemize +@item +Optionally, you might want to create your own custom @samp{gnosis-display} functions +@end itemize + +@node Customizing Gnosis Algorithm +@section Customizing Gnosis Algorithm + +@menu +* Gnosis Algorithm Initial Interval:: +* Gnosis Algorithm Easiness Factor:: +* Gnosis Algorithm Forgetting Factor:: +@end menu @node Gnosis Algorithm Initial Interval -@section Gnosis Algorithm Initial Interval +@subsection Gnosis Algorithm Initial Interval @samp{gnosis-algorithm-interval} is a list of 2 numbers, representing the first two initial intervals for successful reviews. @@ -277,7 +354,7 @@ you will see it again tomorrow, if you successfully review said note again, the next review will be after 3 days. @node Gnosis Algorithm Easiness Factor -@section Gnosis Algorithm Easiness Factor +@subsection Gnosis Algorithm Easiness Factor @samp{gnosis-algorithm-ef} is a list that consists of 3 items. @@ -303,7 +380,7 @@ Example: @end lisp @node Gnosis Algorithm Forgetting Factor -@section Gnosis Algorithm Forgetting Factor +@subsection Gnosis Algorithm Forgetting Factor @samp{gnosis-algorithm-ff} is a floating number below 1. -- cgit v1.2.3