diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/gnosis.info | 229 | ||||
| -rw-r--r-- | doc/gnosis.org | 130 | ||||
| -rw-r--r-- | doc/gnosis.texi | 195 |
3 files changed, 270 insertions, 284 deletions
diff --git a/doc/gnosis.info b/doc/gnosis.info index c654fcb..5176ec6 100644 --- a/doc/gnosis.info +++ b/doc/gnosis.info @@ -2,7 +2,7 @@ This is gnosis.info, produced by makeinfo version 7.1 from gnosis.texi. INFO-DIR-SECTION Emacs misc features START-INFO-DIR-ENTRY -* Gnosis (γνῶσις): (gnosis). Spaced Repetition System For Note Taking And Self-Testing. +* Gnosis (γνῶσις): (gnosis). Spaced Repetition System For Note Taking & Self-Testing. END-INFO-DIR-ENTRY @@ -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.7, released on 2023-02-18. +This manual is written for Gnosis version 0.1.8, released on 2023-02-21. • Official manual: <https://thanosapollo.org/user-manual/gnosis> • Git repositories: @@ -27,9 +27,11 @@ This manual is written for Gnosis version 0.1.7, released on 2023-02-18. * Installation:: * Adding notes:: * Note Types:: -* Customization & Extension:: +* Customization:: * Gnosis Algorithm:: +* Editing notes:: * Sync between devices:: +* Extending Gnosis:: -- The Detailed Node Listing -- @@ -46,10 +48,10 @@ Note Types * MCQ (Multiple Choice Question):: * y-or-n:: -Customization & Extension +Customization -* Adjust for typos | String Comparison:: -* Creating Custom Note Types:: +* Image size:: +* Typos | String Comparison:: Gnosis Algorithm @@ -57,6 +59,10 @@ Gnosis Algorithm * Easiness Factor:: * Forgetting Factor:: +Extending Gnosis + +* Creating Custom Note Types:: + File: gnosis.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top @@ -132,38 +138,12 @@ File: gnosis.info, Node: Adding notes, Next: Note Types, Prev: Installation, Creating notes for gnosis can be done interactively with: ‘M-x gnosis-add-note’ - Advanced/Power users may prefer to use ‘gnosis-add-note--TYPE’ - - Example: - - (gnosis-add-note--basic :deck "DECK-NAME" - :question "Your Question" - :answer "Answer" - :hint "hint" - :extra "Explanation" - :image "Image displayed before user-input" ;; Optional - :second-image "Image displayed after user-input" ;; Optional - :tags '("tag1" "tag2")) - - By default, the value of image and second image is nil. Their value -must a string, the path of an image, from inside ‘gnosis-images-dir’. - - 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. - - Every note type has these values in common: - - • ‘extra’ string value, extra information/explanation displayed after - user-input - • ‘image’ Image displayed _before_ user input - • ‘second-image’ Image displayed _after_ user input - - The following sections will cover the important differences you have -to know when creating new notes. + When it comes to adding images, you can select images that are inside +‘gnosis-images-dir’. See more customization for *note Image Size: Image +size. -File: gnosis.info, Node: Note Types, Next: Customization & Extension, Prev: Adding notes, Up: Top +File: gnosis.info, Node: Note Types, Next: Customization, Prev: Adding notes, Up: Top 4 Note Types ************ @@ -253,32 +233,33 @@ 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 & Extension, Next: Gnosis Algorithm, Prev: Note Types, Up: Top +File: gnosis.info, Node: Customization, Next: Gnosis Algorithm, Prev: Note Types, Up: Top -5 Customization & Extension -*************************** +5 Customization +*************** -To make development and customization easier, gnosis comes with -‘gnosis-test’ module, that should be used to create a custom database -for testing. +* Menu: - To use ‘gnosis-test’, first you have to ‘(require 'gnosis-test)’ & -run ‘M-x gnosis-test-start’. This will create a new database 'testing' -with random inputs. +* Image size:: +* Typos | String Comparison:: - To exit the testing environment, rerun ‘M-x gnosis-test-start’ and -then enter ‘n’ (no) at the prompt "Start development env?" + +File: gnosis.info, Node: Image size, Next: Typos | String Comparison, Up: Customization -* Menu: +5.1 Image size +============== -* Adjust for typos | String Comparison:: -* Creating Custom Note Types:: +Adjust image size using ‘gnosis-image-height’ & ‘gnosis-image-width’ + + Example: + (setf gnosis-image-height 300 + gnosis-image-width 500) -File: gnosis.info, Node: Adjust for typos | String Comparison, Next: Creating Custom Note Types, Up: Customization & Extension +File: gnosis.info, Node: Typos | String Comparison, Prev: Image size, Up: Customization -5.1 Adjust for typos | String Comparison -======================================== +5.2 Typos | String Comparison +============================= You can adjust ‘gnosis-string-difference’, this is a threshold value for string comparison that determines the maximum acceptable Levenshtein @@ -296,39 +277,7 @@ similar, considering that the latter involves just one additional character." -File: gnosis.info, Node: Creating Custom Note Types, Prev: Adjust for typos | String Comparison, Up: Customization & Extension - -5.2 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: Gnosis Algorithm, Next: Sync between devices, Prev: Customization & Extension, Up: Top +File: gnosis.info, Node: Gnosis Algorithm, Next: Editing notes, Prev: Customization, Up: Top 6 Gnosis Algorithm ****************** @@ -404,9 +353,21 @@ interval was 6 days, the next interval will be 6 * 0.5 = 3 days. (setq gnosis-algorithm-ff 0.5) -File: gnosis.info, Node: Sync between devices, Prev: Gnosis Algorithm, Up: Top +File: gnosis.info, Node: Editing notes, Next: Sync between devices, Prev: Gnosis Algorithm, Up: Top + +7 Editing notes +*************** + + • Currently there are 2 ways for editing notes: + + • You can edit a note after review by pressing ‘e’ + • Open ‘gnosis-dashboard’ with ‘M-x gnosis-dashboard’, find the + note you want to edit and press ‘e’ + + +File: gnosis.info, Node: Sync between devices, Next: Extending Gnosis, Prev: Editing notes, Up: Top -7 Sync between devices +8 Sync between devices ********************** Gnosis uses git to maintain data integrity and facilitate @@ -432,31 +393,81 @@ your configuration: (setf gnosis-vc-auto-push t) (gnosis-vc-pull) ;; Run vc-pull for gnosis on startup - You might as well add + +File: gnosis.info, Node: Extending Gnosis, Prev: Sync between devices, Up: Top + +9 Extending Gnosis +****************** + +To make development and customization easier, gnosis comes with +‘gnosis-test’ module, that should be used to create a custom database +for testing. + + To exit the testing environment, rerun ‘M-x gnosis-test-start’ and +then enter ‘n’ (no) at the prompt "Start development env?" + +* Menu: + +* Creating Custom Note Types:: + + +File: gnosis.info, Node: Creating Custom Note Types, Up: Extending Gnosis + +9.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 Tag Table: -Node: Top246 -Node: Introduction1280 -Node: Installation1760 -Node: Using straightel2037 -Node: Installing manually from source2549 -Node: Adding notes3238 -Node: Note Types4654 -Node: Cloze4878 -Node: Basic Type5851 -Node: Double6129 -Node: MCQ (Multiple Choice Question)6475 -Node: y-or-n6884 -Node: Customization & Extension7310 -Node: Adjust for typos | String Comparison8023 -Node: Creating Custom Note Types8859 -Node: Gnosis Algorithm9969 -Node: Initial Interval10200 -Node: Easiness Factor10707 -Node: Forgetting Factor11612 -Node: Sync between devices12146 +Node: Top244 +Node: Introduction1316 +Node: Installation1796 +Node: Using straightel2073 +Node: Installing manually from source2585 +Node: Adding notes3274 +Node: Note Types3639 +Node: Cloze3851 +Node: Basic Type4824 +Node: Double5102 +Node: MCQ (Multiple Choice Question)5448 +Node: y-or-n5857 +Node: Customization6283 +Node: Image size6468 +Node: Typos | String Comparison6754 +Node: Gnosis Algorithm7529 +Node: Initial Interval7741 +Node: Easiness Factor8248 +Node: Forgetting Factor9153 +Node: Editing notes9687 +Node: Sync between devices10079 +Node: Extending Gnosis11107 +Node: Creating Custom Note Types11562 End Tag Table diff --git a/doc/gnosis.org b/doc/gnosis.org index fe5293c..16d4a15 100644 --- a/doc/gnosis.org +++ b/doc/gnosis.org @@ -4,9 +4,8 @@ #+language: en #+options: ':t toc:nil author:t email:t num:t #+startup: content -#+macro: stable-version 0.1.7 -#+macro: release-date 2023-02-18 -#+macro: development-version 0.1.8-dev +#+macro: stable-version 0.1.8 +#+macro: release-date 2023-02-21 #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -16,7 +15,7 @@ #+texinfo_filename: gnosis.info #+texinfo_dir_category: Emacs misc features #+texinfo_dir_title: Gnosis (γνῶσις): (gnosis) -#+texinfo_dir_desc: Spaced Repetition System For Note Taking And Self-Testing +#+texinfo_dir_desc: Spaced Repetition System For Note Taking & Self-Testing #+texinfo_header: @set MAINTAINERSITE @uref{https://thanosapollo.org,maintainer webpage} #+texinfo_header: @set MAINTAINER Thanos Apollo #+texinfo_header: @set MAINTAINEREMAIL @email{[email protected]} @@ -87,37 +86,8 @@ or you may also install them manually from their repository. Creating notes for gnosis can be done interactively with: =M-x gnosis-add-note= - -Advanced/Power users may prefer to use =gnosis-add-note--TYPE= - -Example: - -#+begin_src emacs-lisp - (gnosis-add-note--basic :deck "DECK-NAME" - :question "Your Question" - :answer "Answer" - :hint "hint" - :extra "Explanation" - :image "Image displayed before user-input" ;; Optional - :second-image "Image displayed after user-input" ;; Optional - :tags '("tag1" "tag2")) -#+end_src - -By default, the value of image and second image is nil. Their value -must a string, the path of an image, from inside ~gnosis-images-dir~. - -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. - -Every note type has these values in common: - - + ~extra~ string value, extra information/explanation displayed after user-input - + ~image~ Image displayed /before/ user input - + ~second-image~ Image displayed /after/ user input - -The following sections will cover the important differences you have -to know when creating new notes. +When it comes to adding images, you can select images that are inside +=gnosis-images-dir=. See more customization for [[Image size][Image Size]] * Note Types ** Cloze @@ -172,20 +142,16 @@ When using the hidden function =gnosis-add-note--y-or-n=, note that the ANSWER must be either 121 (~y~) or 110 (~n~), as those correspond to the character values used to represent them. -* Customization & Extension - -To make development and customization easier, gnosis comes with -=gnosis-test= module, that should be used to create a custom database for -testing. +* Customization +** Image size +Adjust image size using =gnosis-image-height= & =gnosis-image-width= -To use =gnosis-test=, first you have to =(require 'gnosis-test)= & run -=M-x gnosis-test-start=. This will create a new database 'testing' -with random inputs. - -To exit the testing environment, rerun =M-x gnosis-test-start= and -then enter =n= (no) at the prompt "Start development env?" - -** Adjust for typos | String Comparison +Example: +#+begin_src emacs-lisp +(setf gnosis-image-height 300 + gnosis-image-width 500) +#+end_src +** Typos | String Comparison You can adjust =gnosis-string-difference=, this is a threshold value for string comparison that determines the maximum acceptable Levenshtein distance between two strings, which identifies their @@ -204,34 +170,6 @@ To demonstrate, 'example' and 'examples' will be recognized as similar, considering that the latter involves just one additional character." -** 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= - - #+begin_src emacs-lisp - (add-to-list 'gnosis-note-types 'new-type) - #+end_src - -+ 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 - * Gnosis Algorithm ** Initial Interval @@ -292,6 +230,11 @@ Example configuration: (setq gnosis-algorithm-ff 0.5) #+end_src +* Editing notes ++ Currently there are 2 ways for editing notes: + + + You can edit a note after review by pressing ~e~ + + Open =gnosis-dashboard= with =M-x gnosis-dashboard=, find the note you want to edit and press ~e~ * Sync between devices Gnosis uses git to maintain data integrity and facilitate @@ -321,5 +264,38 @@ 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 +testing. + +To exit the testing environment, rerun =M-x gnosis-test-start= and +then enter =n= (no) at the prompt "Start development env?" + +** 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= -You might as well add + #+begin_src emacs-lisp + (add-to-list 'gnosis-note-types 'new-type) + #+end_src + ++ 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 diff --git a/doc/gnosis.texi b/doc/gnosis.texi index 379dc18..745f7ff 100644 --- a/doc/gnosis.texi +++ b/doc/gnosis.texi @@ -12,7 +12,7 @@ @dircategory Emacs misc features @direntry -* Gnosis (γνῶσις): (gnosis). Spaced Repetition System For Note Taking And Self-Testing. +* Gnosis (γνῶσις): (gnosis). Spaced Repetition System For Note Taking & Self-Testing. @end direntry @finalout @@ -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.7, released on 2023-02-18. +This manual is written for Gnosis version 0.1.8, released on 2023-02-21. @itemize @item @@ -51,9 +51,11 @@ Git repositories: * Installation:: * Adding notes:: * Note Types:: -* Customization & Extension:: +* Customization:: * Gnosis Algorithm:: +* Editing notes:: * Sync between devices:: +* Extending Gnosis:: @detailmenu --- The Detailed Node Listing --- @@ -71,10 +73,10 @@ Note Types * MCQ (Multiple Choice Question):: * y-or-n:: -Customization & Extension +Customization -* Adjust for typos | String Comparison:: -* Creating Custom Note Types:: +* Image size:: +* Typos | String Comparison:: Gnosis Algorithm @@ -82,6 +84,10 @@ Gnosis Algorithm * Easiness Factor:: * Forgetting Factor:: +Extending Gnosis + +* Creating Custom Note Types:: + @end detailmenu @end menu @@ -157,42 +163,8 @@ Add this to your emacs configuration Creating notes for gnosis can be done interactively with: @samp{M-x gnosis-add-note} - -Advanced/Power users may prefer to use @samp{gnosis-add-note--TYPE} - -Example: - -@lisp -(gnosis-add-note--basic :deck "DECK-NAME" - :question "Your Question" - :answer "Answer" - :hint "hint" - :extra "Explanation" - :image "Image displayed before user-input" ;; Optional - :second-image "Image displayed after user-input" ;; Optional - :tags '("tag1" "tag2")) -@end lisp - -By default, the value of image and second image is nil. Their value -must a string, the path of an image, from inside @code{gnosis-images-dir}. - -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. - -Every note type has these values in common: - -@itemize -@item -@code{extra} string value, extra information/explanation displayed after user-input -@item -@code{image} Image displayed @emph{before} user input -@item -@code{second-image} Image displayed @emph{after} user input -@end itemize - -The following sections will cover the important differences you have -to know when creating new notes. +When it comes to adding images, you can select images that are inside +@samp{gnosis-images-dir}. See more customization for @ref{Image size, , Image Size} @node Note Types @chapter Note Types @@ -270,27 +242,27 @@ 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 & Extension -@chapter Customization & Extension +@node Customization +@chapter Customization -To make development and customization easier, gnosis comes with -@samp{gnosis-test} module, that should be used to create a custom database for -testing. +@menu +* Image size:: +* Typos | String Comparison:: +@end menu -To use @samp{gnosis-test}, first you have to @samp{(require 'gnosis-test)} & run -@samp{M-x gnosis-test-start}. This will create a new database 'testing' -with random inputs. +@node Image size +@section Image size -To exit the testing environment, rerun @samp{M-x gnosis-test-start} and -then enter @samp{n} (no) at the prompt ``Start development env?'' +Adjust image size using @samp{gnosis-image-height} & @samp{gnosis-image-width} -@menu -* Adjust for typos | String Comparison:: -* Creating Custom Note Types:: -@end menu +Example: +@lisp +(setf gnosis-image-height 300 + gnosis-image-width 500) +@end lisp -@node Adjust for typos | String Comparison -@section Adjust for typos | String Comparison +@node Typos | String Comparison +@section Typos | String Comparison You can adjust @samp{gnosis-string-difference}, this is a threshold value for string comparison that determines the maximum acceptable @@ -310,45 +282,6 @@ To demonstrate, 'example' and 'examples' will be recognized as similar, considering that the latter involves just one additional character.`` -@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 Gnosis Algorithm @chapter Gnosis Algorithm @@ -426,6 +359,21 @@ Example configuration: (setq gnosis-algorithm-ff 0.5) @end lisp +@node Editing notes +@chapter Editing notes + +@itemize +@item +Currently there are 2 ways for editing notes: + +@itemize +@item +You can edit a note after review by pressing @code{e} +@item +Open @samp{gnosis-dashboard} with @samp{M-x gnosis-dashboard}, find the note you want to edit and press @code{e} +@end itemize +@end itemize + @node Sync between devices @chapter Sync between devices @@ -457,6 +405,57 @@ To automatically push changes after a review session, add this to your configura (gnosis-vc-pull) ;; Run vc-pull for gnosis on startup @end lisp -You might as well add +@node Extending Gnosis +@chapter Extending Gnosis + +To make development and customization easier, gnosis comes with +@samp{gnosis-test} module, that should be used to create a custom database for +testing. + +To exit the testing environment, rerun @samp{M-x gnosis-test-start} and +then enter @samp{n} (no) at the prompt ``Start development env?'' + +@menu +* Creating Custom Note Types:: +@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 @bye |