From f5334b5ba4a2bf8bc4e1abbbf5f7890c3891b701 Mon Sep 17 00:00:00 2001 From: Thanos Apollo Date: Sun, 18 Feb 2024 16:33:05 +0200 Subject: doc: Update for version 0.1.7 --- doc/gnosis.org | 100 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 52 insertions(+), 48 deletions(-) (limited to 'doc/gnosis.org') diff --git a/doc/gnosis.org b/doc/gnosis.org index c2ffcf1..b10af7a 100644 --- a/doc/gnosis.org +++ b/doc/gnosis.org @@ -4,9 +4,9 @@ #+language: en #+options: ':t toc:nil author:t email:t num:t #+startup: content -#+macro: stable-version 0.1.5 -#+macro: release-date 2023-01-29 -#+macro: development-version 0.1.6-dev +#+macro: stable-version 0.1.7 +#+macro: release-date 2023-02-18 +#+macro: development-version 0.1.8-dev #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -32,8 +32,7 @@ This manual is written for Gnosis version {{{stable-version}}}, released on {{{r + Official manual: + Git repositories: - + main: - + sourcehut (mirror): + + #+texinfo: @insertcopying @@ -48,10 +47,8 @@ your notes & review sessions, making it easier to study. * Installation -Gnosis is not currently available in any ELPA, the recommended way to -install gnosis is via straight.el: - - +Gnosis is available via MELPA ++ ** Using straight.el If you have not installed straight.el, follow the instructions here: @@ -178,17 +175,18 @@ character values used to represent them. * Customization & Extension To make development and customization easier, gnosis comes with -=gnosis-dev= module, that should be used to create a custom database for +=gnosis-test= 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 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?" -To exit the testing environment, rerun =M-x gnosis-dev-test= and then -enter =n= (no) at the prompt "Start development env?" -** Adjust string comparison -You may adjust =gnosis-string-difference=, this is a threshold value +** Adjust for 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 similarity @@ -198,7 +196,7 @@ Let's illustrate with an example: (setf gnosis-string-difference 1) #+end_src -In this scenario, we set `gnosis-string-difference` to 1. This implies +In this scenario, we set =gnosis-string-difference= to 1. This implies that two strings will be recognized as similar if they exhibit a difference of at most one character edit. @@ -207,6 +205,7 @@ 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= @@ -233,8 +232,8 @@ this should be done. + Optionally, you might want to create your own custom =gnosis-display= functions -** Customizing Gnosis Algorithm -*** Gnosis Algorithm Initial Interval +* Gnosis Algorithm +** Initial Interval =gnosis-algorithm-interval= is a list of 2 numbers, representing the first two initial intervals for successful reviews. @@ -249,56 +248,61 @@ 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. -*** Gnosis Algorithm Easiness Factor +** Easiness Factor -=gnosis-algorithm-ef= is a list that consists of 3 items. +The =gnosis-algorithm-ef= is a list that consists of three items: -The first item is the increase factor, used to increase the easiness -factor upon successful review. +1. Easiness factor increase value: Added to the easiness factor upon a + successful review. + +2. Easiness factor decrease value: Subtracted from the total easiness + factor upon a failed review. + +3. Initial total easiness factor: Used to calculate the next interval. -Second item refers to the decrease factor, used to -decrease the easiness factor upon an unsuccessful review. ++ How this is used: + +Multiplies the last interval by the easiness factor after a successful +review. -The third item is the initial total easiness factor, used to calculate -the next interval. +For example, if the last review was 6 days ago with an easiness factor +of 2.0, the next interval would be calculated as 6 * 2.0, and the +total easiness factor would be updated by adding the increase factor. -The basic's of how this is used is that it's being multiplied with the -last interval upon a successful review, e.g if you last reviewed a -note 6 days ago, and the easiness factor of this note is 2.0, your -next interval would be 6 * 2.0 & the total easiness factor would be -2.0 + increase-factor as well. - -Example: +Configuration example: #+begin_src emacs-lisp - (setq gnosis-algorithm-ef '(0.3 0.3 1.3)) + (setq gnosis-algorithm-ef '(0.30 0.25 1.3)) #+end_src -*** Gnosis Algorithm Forgetting Factor +** Forgetting Factor =gnosis-algorithm-ff= is a floating number below 1. -It's used to calculate the next interval upon an unsuccessful review, -by being multiplied with last interval. +Used to determine the next interval after an unsuccessful review. +Multiplied with the last interval to calculate the next interval. For +example, if =gnosis-algorithm-ff= is set to 0.5 and the last interval +was 6 days, the next interval will be 6 * 0.5 = 3 days. -Example: +Example configuration: #+begin_src emacs-lisp (setq gnosis-algorithm-ff 0.5) #+end_src -For a note with a value of last-interval of 6 days and a ff of 0.5, -upon an unsuccessful review the next interval will be 6 * 0.5 +** Auto push changes +You can interactively use =gnosis-vc-push= & =gnosis-vc-pull=. -** Auto push changes -When setting =gnosis-auto-push= to =t=, at the end of every review -session the changes to ~gnosis-db~ will be pushed to the pre-configured -push remote. You have to set your push remote manually. +As the name suggests, they rely on =vc= to work properly. -#+begin_src emacs-lisp -(setf gnosis-auto-push t) +Make sure you have setup a git remote for gnosis. +#+begin_src bash + cd ~//gnosis # default location for gnosis + git remote add # #+end_src +Depending on your setup, =vc= might require an external package for +the ssh passphrase dialog, such as ~x11-ssh-askpass~. -- cgit v1.2.3