summaryrefslogtreecommitdiff
path: root/doc/gnosis.org
diff options
context:
space:
mode:
authorThanos Apollo <[email protected]>2024-02-18 16:33:05 +0200
committerThanos Apollo <[email protected]>2024-02-18 16:33:05 +0200
commitf5334b5ba4a2bf8bc4e1abbbf5f7890c3891b701 (patch)
tree9b16a5b73d66c09611d32955ffec38fcaf489ef5 /doc/gnosis.org
parent6a91e428cdb78c9f2add0aadc27c4509f11aff08 (diff)
doc: Update for version 0.1.7
Diffstat (limited to 'doc/gnosis.org')
-rw-r--r--doc/gnosis.org100
1 files changed, 52 insertions, 48 deletions
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: <https://thanosapollo.org/user-manual/gnosis>
+ Git repositories:
- + main: <https://git.thanosapollo.org/gnosis>
- + sourcehut (mirror): <https://git.sr.ht/~thanosapollo/gnosis>
+ + <https://git.thanosapollo.org/gnosis>
#+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:
-
- <https://github.com/radian-software/straight.el>
+Gnosis is available via MELPA
++ <https://melpa.org/#/gnosis>
** 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 ~/<your-emacs-directory>/gnosis # default location for gnosis
+ git remote add <remote_name> <remote_url> #
#+end_src
+Depending on your setup, =vc= might require an external package for
+the ssh passphrase dialog, such as ~x11-ssh-askpass~.