branch: externals/org-gnosis
commit 1287e5181400a5c5ab6b93bd5137afcf909300b6
Author: Thanos Apollo <pub...@thanosapollo.org>
Commit: Thanos Apollo <pub...@thanosapollo.org>
doc: Update configuration & use-package snippet example.
---
doc/org-gnosis.info | 443 +++++++++++++++++++++++++++++++++++++++++++++++++++
doc/org-gnosis.org | 94 +++++++++--
doc/org-gnosis.texi | 449 ++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 971 insertions(+), 15 deletions(-)
diff --git a/doc/org-gnosis.info b/doc/org-gnosis.info
new file mode 100644
index 0000000000..154f54b181
--- /dev/null
+++ b/doc/org-gnosis.info
@@ -0,0 +1,443 @@
+This is org-gnosis.info, produced by .texi2any-real version 7.1.1 from
+org-gnosis.texi.
+
+Copyright (C) 2025 Free Software Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with no Invariant Sections, with the Front-Cover Texts
+ being “A GNU Manual,” and with the Back-Cover Texts as in (a)
+ below. A copy of the license is included in the section entitled
+ “GNU Free Documentation License.”
+
+ (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
+ modify this GNU manual.”
+
+INFO-DIR-SECTION Emacs misc features
+START-INFO-DIR-ENTRY
+* Org Gnosis : (org-gnosis). Roam-like Knowledge Management System.
+END-INFO-DIR-ENTRY
+
+
+File: org-gnosis.info, Node: Top, Next: Installation & Configuration, Up:
(dir)
+
+Org Gnosis User Manual
+**********************
+
+Copyright (C) 2025 Free Software Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with no Invariant Sections, with the Front-Cover Texts
+ being “A GNU Manual,” and with the Back-Cover Texts as in (a)
+ below. A copy of the license is included in the section entitled
+ “GNU Free Documentation License.”
+
+ (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
+ modify this GNU manual.”
+
+ This manual, authored by Thanos Apollo, offers installation
+instructions, customization options, and recommendations for effectively
+using ‘org-gnosis’.
+
+ The documentation furnished herein corresponds to stable version
+0.0.4, released on 2025-02-13.
+
+ • Name: Org Gnosis | Organization Of Gnosis (knowledge/information)
+ • Homepage: <https://thanosapollo.org/projects/org-gnosis/>
+
+ Org Gnosis (GNU-sis) is an org-mode parsing tool that organizes notes
+as atomic nodes in an SQLite database. Each heading with an ID is
+treated as an atomic note (node), storing its metadata, such as title
+and links, in a relational database to facilitate efficient linking and
+navigation.
+
+ This tool also offers special functionality for journal entries,
+stored in a separate directory with support for customizable templates.
+This can serve as an additional space for temporary notes.
+
+* Menu:
+
+* Installation & Configuration::
+* Taking Notes With Org Gnosis::
+* Configuration::
+* Contributing::
+
+-- The Detailed Node Listing --
+
+Taking Notes With Org Gnosis
+
+* Organizing your notes::
+* Importing Notes::
+
+Configuration
+
+* Completions::
+* Encryption::
+
+Completions
+
+* Diacritic Insensitive completions::
+
+Contributing
+
+* Sources::
+* Patches Require Copyright Assignment To The FSF::
+
+
+
+File: org-gnosis.info, Node: Installation & Configuration, Next: Taking
Notes With Org Gnosis, Prev: Top, Up: Top
+
+1 Installation & Configuration
+******************************
+
+ • The ‘org-gnosis’ package is available from the GNU ELPA archive,
+ which is enabled by default.
+
+ • Prior to querying an archive, make sure to update the index,
+ with ‘M-x package-refresh-contents’.
+
+ • Then all you need to do is type ‘M-x package-install’ and specify
+ the ‘org-gnosis’ package.
+
+ Example installation & configuration using ‘use-package’
+ (use-package org-gnosis
+ :ensure t
+ :init
+ ;; Example for separated journaling & notes keymap
+ (define-prefix-command 'my/notes-map)
+ (define-prefix-command 'my/journal-map)
+ :config
+ (defun example/org-gnosis-book-template ()
+ (let ((date (format-time-string "%Y-%m-%d"))
+ (book-title (completing-read
+ "Example book: "
+ '("Free Software, Free Society" "How to Take Smart
Notes"))))
+ (format "#+DATE: %s \n#+BOOK_TITLE: %s\n\n* Main Idea\n* Key
Points\n* Own Thoughts"
+ date book-title)))
+
+ (add-to-list 'org-gnosis-node-templates
+ '("Book Example" example/org-gnosis-book-template))
+ :bind (("C-c n" . thanos/notes-map)
+ ("C-c n j" . thanos/journal-map)
+ :map thanos/notes-map
+ ("f" . org-gnosis-find)
+ ("i" . org-gnosis-insert)
+ ("t" . org-gnosis-find-by-tag)
+ :map thanos/journal-map
+ ("j" . org-gnosis-journal)
+ ("f" . org-gnosis-journal-find)
+ ("i" . org-gnosis-journal-insert)
+ :map org-gnosis-mode-map
+ ("C-c C-." . org-gnosis-insert-tag)
+ ("C-c i" . org-id-get-create))
+ :custom
+ (org-gnosis-dir "~/Notes")
+ ;; Whe non-nil, create notes as gpg encrypted files, see epa config
+ (org-gnosis-create-as-gpg t)
+ ;; TODO files, commonly used for templates.
+ (org-gnosis-todo-files org-agenda-files)
+ ;; Used in #'org-gnosis-todos for template generation
+ (org-gnosis-bullet-point-char "+")
+ ;; Default completing-read function
+ (org-gnosis-completing-read-func #'org-completing-read)
+ ;; Recommended if you use a vertical completion system (e.g vertico)
+ (org-gnosis-show-tags t))
+
+ • See *note Encryption:: for recommended settings when using ‘gpg’
+
+
+File: org-gnosis.info, Node: Taking Notes With Org Gnosis, Next:
Configuration, Prev: Installation & Configuration, Up: Top
+
+2 Taking Notes With Org Gnosis
+******************************
+
+For Org Gnosis there are 2 types of notes,
+
+ • Your "permanent" notes, which you can visit & and create using ‘M-x
+ org-gnosis-find’
+
+ • Your journal notes, which you can visit & create using ‘M-x
+ org-gnosis-journal-find’, which optionally can serve as "fleeting"
+ notes.
+
+ As mentioned before, opening & searching your notes should be done
+using ‘M-x org-gnosis-find’ as this will enable ‘org-gnosis-mode’.
+
+ If ‘org-gnosis-mode’ is not enabled, files will not be parsed and
+saved in the database when you run ‘save-buffer’.
+
+ Org Gnosis does not automatically sync the database. To delete a
+file, use ‘org-gnosis-delete-file’ or run ‘org-gnosis-db-sync’ after
+manual deletion.
+
+* Menu:
+
+* Organizing your notes::
+* Importing Notes::
+
+
+File: org-gnosis.info, Node: Organizing your notes, Next: Importing Notes,
Up: Taking Notes With Org Gnosis
+
+2.1 Organizing your notes
+=========================
+
+‘org-gnosis’ provides a zettelkasten-inspired approach to note-taking,
+treating knowledge (gnosis) as valuable and not merely something to be
+boxed into a single category, to be disposed after a certain period of
+time or task accomplishment.
+
+ Using directories to organize your notes is not recommended, a
+preferred method is to create *MOC* files (Maps Of Contents) for
+specific categories/projects that you are working on.
+
+ An MOC file can be the syllabus of a class or a project road map.
+For example, you might create an MOC like this for a class on
+‘Biopolymers’:
+
+ • First create a node using ‘M-x org-gnosis-find’ followed by
+ ‘Biopolymers’, which will be created if it does not already exist.
+ • Use ‘M-x org-gnosis-insert-tags’ to insert ‘moc’ tag.
+ • Start inserting your syllabus points with ‘M-x org-gnosis-insert’
+ as nodes, which will be automatically created & saved in separated
+ files.
+
+ Example:
+ :PROPERTIES:
+ :ID: 15edada1-9815-4fb3-9b8f-7da08107bdb2
+ :END:
+ #+title: Biopolymers Syllabus
+ #+filetags: :moc:
+
+ * Proteins
+ - Protein Structure Levels
+ - Protein Domains
+ - Protein MOTIF
+ - Difference between a motif and a domain in a protein
+ - Protein Families
+
+ * Nucleic acids
+ - DNA
+ - RNA
+ - Recognition and self-assembly of macromolecules
+ - Cytoskeleton
+
+ Note: Items with ‘-’ would be links. The headings in the above
+example could be links to an MOC as well.
+
+ This way your notes are atomic & can be reused in future
+classes/projects.
+
+ • For example you'd reuse your notes on nucleic acids in a genetics
+ class MOC for your next semester.
+
+
+File: org-gnosis.info, Node: Importing Notes, Prev: Organizing your notes,
Up: Taking Notes With Org Gnosis
+
+2.2 Importing Notes
+===================
+
+If you are a previous user of packages that use ‘org-mode’ and org ids,
+your current note collection should be able to work with ‘org-gnosis’
+without you having to change anything.
+
+ To sync your note collection use ‘M-x org-gnosis-db-sync’
+
+
+File: org-gnosis.info, Node: Configuration, Next: Contributing, Prev:
Taking Notes With Org Gnosis, Up: Top
+
+3 Configuration
+***************
+
+* Menu:
+
+* Completions::
+* Encryption::
+
+
+File: org-gnosis.info, Node: Completions, Next: Encryption, Up:
Configuration
+
+3.1 Completions
+===============
+
+To customize completions of ‘org-gnosis’, you can adjust the value
+‘org-gnosis-completing-read-func’.
+
+* Menu:
+
+* Diacritic Insensitive completions::
+
+
+File: org-gnosis.info, Node: Diacritic Insensitive completions, Up:
Completions
+
+3.1.1 Diacritic Insensitive completions
+---------------------------------------
+
+If you want to have diacritic insensitive completions you can use
+something like this:
+
+ (use-package ucs-normalize
+ :functions (my/strip-diacritics)
+ :config
+ (defun my/strip-diacritics (s)
+ "Remove diacritics from string S."
+ (let ((decomposed (ucs-normalize-NFD-string s)))
+ (replace-regexp-in-string "\\p{Mn}+" "" decomposed))))
+
+ (use-package org-gnosis
+ :ensure t
+ :after ucs-normalize
+ :config
+ (defun my/completing-read (prompt collection)
+ "Prompt user with completing-read that ignores diacritics on
completion.
+ Useful if you write in langs like Greek :)."
+ (let* ((stripped-alist (mapcar (lambda (item)
+ (cons (my/strip-diacritics item)
item))
+ collection))
+ (map (let ((m (make-sparse-keymap)))
+ (set-keymap-parent m minibuffer-local-completion-map)
+ (define-key m " " #'self-insert-command)
+ m))
+ (completion-table
+ (lambda (string pred action)
+ (if (eq action 'metadata)
+ '(metadata (category . diacritic-completion))
+ (complete-with-action
+ action stripped-alist
+ (my/strip-diacritics string) pred))))
+ (result (minibuffer-with-setup-hook
+ (lambda () (use-local-map map))
+ (completing-read prompt completion-table))))
+ (or (cdr (assoc result stripped-alist)) result)))
+ :custom
+ (org-gnosis-completing-read-func #'my/completing-read))
+
+
+File: org-gnosis.info, Node: Encryption, Prev: Completions, Up:
Configuration
+
+3.2 Encryption
+==============
+
+Emacs provides built-in support for GPG encryption through ‘epg’ and
+‘epa’.
+
+ You can use ‘epa’ (EasyPG Assistant) to customize how you want your
+files encrypted, such as setting a default key to encrypt your files.
+
+ Example:
+ (use-package epa
+ :defer t
+ :config
+ (setf epa-keys-select-method 'minibuffer
+ epa-file-encrypt-to '("62B758D0F6719938BC09CECA339F736C3A720928")
+ ;; Do not prompt for key selection, we are only using the above
key.
+ epa-file-select-keys 'silent))
+
+
+
+File: org-gnosis.info, Node: Contributing, Prev: Configuration, Up: Top
+
+4 Contributing
+**************
+
+* Menu:
+
+* Sources::
+* Patches Require Copyright Assignment To The FSF::
+
+
+File: org-gnosis.info, Node: Sources, Next: Patches Require Copyright
Assignment To The FSF, Up: Contributing
+
+4.1 Sources
+===========
+
+ • Main repository: <https://git.thanosapollo.org/org-gnosis/>
+ • Mirrors:
+ • <https://codeberg.org/thanosapollo/emacs-org-gnosis>
+
+
+File: org-gnosis.info, Node: Patches Require Copyright Assignment To The FSF,
Prev: Sources, Up: Contributing
+
+4.2 Patches Require Copyright Assignment To The FSF
+===================================================
+
+Code contributions are most welcome. For any major edit (more than 15
+lines, or so, in aggregate per person), you need to make a copyright
+assignment to the Free Software Foundation. This is necessary as the
+FSF must at all times be in a position to enforce the GNU General Public
+License.
+
+ Here’s the process:
+
+ 1. Review and adapt the request form below.
+ 2. Email the specified address with your request.
+ 3. Await a legal agreement from the FSF.
+ 4. Sign and return the document, which can be done via email.
+
+ The entire process usually takes about a week and needs to be
+completed only once, allowing you to contribute to GNU Emacs.
+
+ Please email the following information to ass...@gnu.org, and we
+ will send you the assignment form for your past and future changes.
+
+ Please use your full legal name (in ASCII characters) as the subject
+ line of the message.
+
+ REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES
+
+ [Additional people we should notify about the progress of the assignment.]
+
+ Thanos Apollo <pub...@thanosapollo.org>
+
+ [What is the name of the program or package you're contributing to?]
+
+ Emacs
+
+ [Did you copy any files or text written by someone else in these changes?
+ Even if that material is free software, we need to know about it.]
+
+
+ [Do you have an employer who might have a basis to claim to own
+ your changes? Do you attend a school which might make such a claim?]
+
+
+ [For the copyright registration, what country are you a citizen of?]
+
+
+ [What year were you born?]
+
+
+ [Please write your email address here.]
+
+
+ [Please write your postal address here.]
+
+
+ [Which files have you changed so far, and which new files have you written
+ so far?]
+
+
+
+
+Tag Table:
+Node: Top858
+Node: Installation & Configuration2909
+Node: Taking Notes With Org Gnosis5474
+Node: Organizing your notes6464
+Node: Importing Notes8348
+Node: Configuration8759
+Node: Completions8948
+Node: Diacritic Insensitive completions9224
+Node: Encryption11121
+Node: Contributing11787
+Node: Sources11970
+Node: Patches Require Copyright Assignment To The FSF12260
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/doc/org-gnosis.org b/doc/org-gnosis.org
index e2b5c218c7..7a36265dbf 100644
--- a/doc/org-gnosis.org
+++ b/doc/org-gnosis.org
@@ -82,19 +82,6 @@ Example installation & configuration using ~use-package~
(define-prefix-command 'my/notes-map)
(define-prefix-command 'my/journal-map)
:config
- ;; Common settings you might want to tweak to your liking
- (setf org-gnosis-dir "~/Notes"
- ;; Whe non-nil, create notes as gpg encrypted files
- org-gnosis-create-as-gpg nil
- ;; TODO files, commonly used for templates.
- org-gnosis-todo-files org-agenda-files
- ;; Used in #'org-gnosis-todos for template generation
- org-gnosis-bullet-point-char "+"
- ;; Default completing-read function
- org-gnosis-completing-read-func #'org-completing-read
- ;; Recommended if you use a vertical completion system (e.g vertico)
- org-gnosis-show-tags t)
-
(defun example/org-gnosis-book-template ()
(let ((date (format-time-string "%Y-%m-%d"))
(book-title (completing-read
@@ -115,10 +102,24 @@ Example installation & configuration using ~use-package~
("j" . org-gnosis-journal)
("f" . org-gnosis-journal-find)
("i" . org-gnosis-journal-insert)
- :map org-mode-map
+ :map org-gnosis-mode-map
("C-c C-." . org-gnosis-insert-tag)
- ("C-c i" . org-id-get-create)))
+ ("C-c i" . org-id-get-create))
+ :custom
+ (org-gnosis-dir "~/Notes")
+ ;; Whe non-nil, create notes as gpg encrypted files, see epa config
+ (org-gnosis-create-as-gpg t)
+ ;; TODO files, commonly used for templates.
+ (org-gnosis-todo-files org-agenda-files)
+ ;; Used in #'org-gnosis-todos for template generation
+ (org-gnosis-bullet-point-char "+")
+ ;; Default completing-read function
+ (org-gnosis-completing-read-func #'org-completing-read)
+ ;; Recommended if you use a vertical completion system (e.g vertico)
+ (org-gnosis-show-tags t))
#+end_src
+
++ See [[Encryption]] for recommended settings when using =gpg=
* Taking Notes With Org Gnosis
For Org Gnosis there are 2 types of notes,
@@ -200,6 +201,69 @@ ids, your current note collection should be able to work
with
~org-gnosis~ without you having to change anything.
To sync your note collection use {{{kbd(M-x org-gnosis-db-sync)}}}
+* Configuration
+** Completions
+To customize completions of =org-gnosis=, you can adjust the value
+=org-gnosis-completing-read-func=.
+*** Diacritic Insensitive completions
+If you want to have diacritic insensitive completions you can use
+something like this:
+
+#+begin_src emacs-lisp
+ (use-package ucs-normalize
+ :functions (my/strip-diacritics)
+ :config
+ (defun my/strip-diacritics (s)
+ "Remove diacritics from string S."
+ (let ((decomposed (ucs-normalize-NFD-string s)))
+ (replace-regexp-in-string "\\p{Mn}+" "" decomposed))))
+
+ (use-package org-gnosis
+ :ensure t
+ :after ucs-normalize
+ :config
+ (defun my/completing-read (prompt collection)
+ "Prompt user with completing-read that ignores diacritics on completion.
+ Useful if you write in langs like Greek :)."
+ (let* ((stripped-alist (mapcar (lambda (item)
+ (cons (my/strip-diacritics item) item))
+ collection))
+ (map (let ((m (make-sparse-keymap)))
+ (set-keymap-parent m minibuffer-local-completion-map)
+ (define-key m " " #'self-insert-command)
+ m))
+ (completion-table
+ (lambda (string pred action)
+ (if (eq action 'metadata)
+ '(metadata (category . diacritic-completion))
+ (complete-with-action
+ action stripped-alist
+ (my/strip-diacritics string) pred))))
+ (result (minibuffer-with-setup-hook
+ (lambda () (use-local-map map))
+ (completing-read prompt completion-table))))
+ (or (cdr (assoc result stripped-alist)) result)))
+ :custom
+ (org-gnosis-completing-read-func #'my/completing-read))
+#+end_src
+** Encryption
+Emacs provides built-in support for GPG encryption through =epg= and
+=epa=.
+
+You can use =epa= (EasyPG Assistant) to customize how you want your
+files encrypted, such as setting a default key to encrypt your files.
+
+Example:
+#+begin_src emacs-lisp
+ (use-package epa
+ :defer t
+ :config
+ (setf epa-keys-select-method 'minibuffer
+ epa-file-encrypt-to '("62B758D0F6719938BC09CECA339F736C3A720928")
+ ;; Do not prompt for key selection, we are only using the above key.
+ epa-file-select-keys 'silent))
+
+#+end_src
* Contributing
** Sources
+ Main repository: <https://git.thanosapollo.org/org-gnosis/>
diff --git a/doc/org-gnosis.texi b/doc/org-gnosis.texi
new file mode 100644
index 0000000000..6085a1014b
--- /dev/null
+++ b/doc/org-gnosis.texi
@@ -0,0 +1,449 @@
+\input texinfo @c -*- texinfo -*-
+@c %**start of header
+@setfilename org-gnosis.info
+@settitle Org Gnosis User Manual
+@documentencoding UTF-8
+@documentlanguage en
+@set MAINTAINERSITE @uref{https://thanosapollo.org,maintainer webpage}
+@set MAINTAINER Thanos Apollo
+@set MAINTAINEREMAIL @email{pub...@thanosapollo.org}
+@set MAINTAINERCONTACT @uref{mailto:pub...@thanosapollo.org,contact the
maintainer}
+@c %**end of header
+
+@copying
+Copyright (C) 2025 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and
+with the Back-Cover Texts as in (a) below. A copy of the license is
+included in the section entitled “GNU Free Documentation License.”
+
+(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
+modify this GNU manual.”
+
+@end quotation
+@end copying
+
+@dircategory Emacs misc features
+@direntry
+* Org Gnosis : (org-gnosis). Roam-like Knowledge Management System.
+@end direntry
+
+@finalout
+@titlepage
+@title Org Gnosis User Manual
+@author Thanos Apollo (@email{public@@thanosapollo.org})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top
+@top Org Gnosis User Manual
+
+@insertcopying
+
+This manual, authored by Thanos Apollo, offers installation
+instructions, customization options, and recommendations for
+effectively using @code{org-gnosis}.
+
+The documentation furnished herein corresponds to stable version
+0.0.4, released on 2025-02-13.
+
+@itemize
+@item
+Name: Org Gnosis | Organization Of Gnosis (knowledge/information)
+@item
+Homepage: @uref{https://thanosapollo.org/projects/org-gnosis/}
+@end itemize
+
+Org Gnosis (GNU-sis) is an org-mode parsing tool that organizes notes
+as atomic nodes in an SQLite database. Each heading with an ID is
+treated as an atomic note (node), storing its metadata, such as title
+and links, in a relational database to facilitate efficient linking
+and navigation.
+
+This tool also offers special functionality for journal entries,
+stored in a separate directory with support for customizable
+templates. This can serve as an additional space for temporary notes.
+
+@end ifnottex
+
+@menu
+* Installation & Configuration::
+* Taking Notes With Org Gnosis::
+* Configuration::
+* Contributing::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Taking Notes With Org Gnosis
+
+* Organizing your notes::
+* Importing Notes::
+
+Configuration
+
+* Completions::
+* Encryption::
+
+Completions
+
+* Diacritic Insensitive completions::
+
+Contributing
+
+* Sources::
+* Patches Require Copyright Assignment To The FSF::
+
+@end detailmenu
+@end menu
+
+@node Installation & Configuration
+@chapter Installation & Configuration
+
+@itemize
+@item
+The @code{org-gnosis} package is available from the GNU ELPA archive,
+which is enabled by default.
+
+@itemize
+@item
+Prior to querying an archive, make sure to update the index, with
+@kbd{M-x package-refresh-contents}.
+@end itemize
+
+@item
+Then all you need to do is type @kbd{M-x package-install} and
+specify the @code{org-gnosis} package.
+@end itemize
+
+Example installation & configuration using @code{use-package}
+@lisp
+(use-package org-gnosis
+ :ensure t
+ :init
+ ;; Example for separated journaling & notes keymap
+ (define-prefix-command 'my/notes-map)
+ (define-prefix-command 'my/journal-map)
+ :config
+ (defun example/org-gnosis-book-template ()
+ (let ((date (format-time-string "%Y-%m-%d"))
+ (book-title (completing-read
+ "Example book: "
+ '("Free Software, Free Society" "How to Take Smart
Notes"))))
+ (format "#+DATE: %s \n#+BOOK_TITLE: %s\n\n* Main Idea\n* Key Points\n*
Own Thoughts"
+ date book-title)))
+
+ (add-to-list 'org-gnosis-node-templates
+ '("Book Example" example/org-gnosis-book-template))
+ :bind (("C-c n" . thanos/notes-map)
+ ("C-c n j" . thanos/journal-map)
+ :map thanos/notes-map
+ ("f" . org-gnosis-find)
+ ("i" . org-gnosis-insert)
+ ("t" . org-gnosis-find-by-tag)
+ :map thanos/journal-map
+ ("j" . org-gnosis-journal)
+ ("f" . org-gnosis-journal-find)
+ ("i" . org-gnosis-journal-insert)
+ :map org-gnosis-mode-map
+ ("C-c C-." . org-gnosis-insert-tag)
+ ("C-c i" . org-id-get-create))
+ :custom
+ (org-gnosis-dir "~/Notes")
+ ;; Whe non-nil, create notes as gpg encrypted files, see epa config
+ (org-gnosis-create-as-gpg t)
+ ;; TODO files, commonly used for templates.
+ (org-gnosis-todo-files org-agenda-files)
+ ;; Used in #'org-gnosis-todos for template generation
+ (org-gnosis-bullet-point-char "+")
+ ;; Default completing-read function
+ (org-gnosis-completing-read-func #'org-completing-read)
+ ;; Recommended if you use a vertical completion system (e.g vertico)
+ (org-gnosis-show-tags t))
+@end lisp
+
+@itemize
+@item
+See @ref{Encryption} for recommended settings when using @samp{gpg}
+@end itemize
+
+@node Taking Notes With Org Gnosis
+@chapter Taking Notes With Org Gnosis
+
+For Org Gnosis there are 2 types of notes,
+
+@itemize
+@item
+Your ``permanent'' notes, which you can visit & and create using @kbd{M-x
org-gnosis-find}
+
+@item
+Your journal notes, which you can visit & create using @kbd{M-x
org-gnosis-journal-find}, which optionally can serve as
+``fleeting'' notes.
+@end itemize
+
+As mentioned before, opening & searching your notes should be done
+using @kbd{M-x org-gnosis-find} as this will enable
+@samp{org-gnosis-mode}.
+
+If @samp{org-gnosis-mode} is not enabled, files will not be parsed and
+saved in the database when you run @samp{save-buffer}.
+
+Org Gnosis does not automatically sync the database. To delete a file,
+use @samp{org-gnosis-delete-file} or run @samp{org-gnosis-db-sync} after manual
+deletion.
+
+@menu
+* Organizing your notes::
+* Importing Notes::
+@end menu
+
+@node Organizing your notes
+@section Organizing your notes
+
+@code{org-gnosis} provides a zettelkasten-inspired approach to note-taking,
+treating knowledge (gnosis) as valuable and not merely something to be
+boxed into a single category, to be disposed after a certain period of
+time or task accomplishment.
+
+Using directories to organize your notes is not recommended, a
+preferred method is to create @strong{MOC} files (Maps Of Contents) for
+specific categories/projects that you are working on.
+
+An MOC file can be the syllabus of a class or a project road map. For
+example, you might create an MOC like this for a class on
+@code{Biopolymers}:
+
+@itemize
+@item
+First create a node using @kbd{M-x org-gnosis-find} followed by
+@code{Biopolymers}, which will be created if it does not already exist.
+@item
+Use @kbd{M-x org-gnosis-insert-tags} to insert @code{moc} tag.
+@item
+Start inserting your syllabus points with @kbd{M-x org-gnosis-insert} as
nodes, which will be automatically created
+& saved in separated files.
+@end itemize
+
+Example:
+@example
+:PROPERTIES:
+:ID: 15edada1-9815-4fb3-9b8f-7da08107bdb2
+:END:
+#+title: Biopolymers Syllabus
+#+filetags: :moc:
+
+* Proteins
+- Protein Structure Levels
+- Protein Domains
+- Protein MOTIF
+- Difference between a motif and a domain in a protein
+- Protein Families
+
+* Nucleic acids
+- DNA
+- RNA
+- Recognition and self-assembly of macromolecules
+- Cytoskeleton
+
+@end example
+Note: Items with @samp{-} would be links. The headings in the above
+example could be links to an MOC as well.
+
+This way your notes are atomic & can be reused in future
+classes/projects.
+
+@itemize
+@item
+For example you'd reuse your notes on nucleic acids in a genetics
+class MOC for your next semester.
+@end itemize
+
+@node Importing Notes
+@section Importing Notes
+
+If you are a previous user of packages that use @code{org-mode} and org
+ids, your current note collection should be able to work with
+@code{org-gnosis} without you having to change anything.
+
+To sync your note collection use @kbd{M-x org-gnosis-db-sync}
+
+@node Configuration
+@chapter Configuration
+
+@menu
+* Completions::
+* Encryption::
+@end menu
+
+@node Completions
+@section Completions
+
+To customize completions of @samp{org-gnosis}, you can adjust the value
+@samp{org-gnosis-completing-read-func}.
+
+@menu
+* Diacritic Insensitive completions::
+@end menu
+
+@node Diacritic Insensitive completions
+@subsection Diacritic Insensitive completions
+
+If you want to have diacritic insensitive completions you can use
+something like this:
+
+@lisp
+(use-package ucs-normalize
+ :functions (my/strip-diacritics)
+ :config
+ (defun my/strip-diacritics (s)
+ "Remove diacritics from string S."
+ (let ((decomposed (ucs-normalize-NFD-string s)))
+ (replace-regexp-in-string "\\p@{Mn@}+" "" decomposed))))
+
+(use-package org-gnosis
+ :ensure t
+ :after ucs-normalize
+ :config
+ (defun my/completing-read (prompt collection)
+ "Prompt user with completing-read that ignores diacritics on completion.
+Useful if you write in langs like Greek :)."
+ (let* ((stripped-alist (mapcar (lambda (item)
+ (cons (my/strip-diacritics item) item))
+ collection))
+ (map (let ((m (make-sparse-keymap)))
+ (set-keymap-parent m minibuffer-local-completion-map)
+ (define-key m " " #'self-insert-command)
+ m))
+ (completion-table
+ (lambda (string pred action)
+ (if (eq action 'metadata)
+ '(metadata (category . diacritic-completion))
+ (complete-with-action
+ action stripped-alist
+ (my/strip-diacritics string) pred))))
+ (result (minibuffer-with-setup-hook
+ (lambda () (use-local-map map))
+ (completing-read prompt completion-table))))
+ (or (cdr (assoc result stripped-alist)) result)))
+ :custom
+ (org-gnosis-completing-read-func #'my/completing-read))
+@end lisp
+
+@node Encryption
+@section Encryption
+
+Emacs provides built-in support for GPG encryption through @samp{epg} and
+@samp{epa}.
+
+You can use @samp{epa} (EasyPG Assistant) to customize how you want your
+files encrypted, such as setting a default key to encrypt your files.
+
+Example:
+@lisp
+(use-package epa
+ :defer t
+ :config
+ (setf epa-keys-select-method 'minibuffer
+ epa-file-encrypt-to '("62B758D0F6719938BC09CECA339F736C3A720928")
+ ;; Do not prompt for key selection, we are only using the above key.
+ epa-file-select-keys 'silent))
+
+@end lisp
+
+@node Contributing
+@chapter Contributing
+
+@menu
+* Sources::
+* Patches Require Copyright Assignment To The FSF::
+@end menu
+
+@node Sources
+@section Sources
+
+@itemize
+@item
+Main repository: @uref{https://git.thanosapollo.org/org-gnosis/}
+@item
+Mirrors:
+@itemize
+@item
+@uref{https://codeberg.org/thanosapollo/emacs-org-gnosis}
+@end itemize
+@end itemize
+
+@node Patches Require Copyright Assignment To The FSF
+@section Patches Require Copyright Assignment To The FSF
+
+Code contributions are most welcome. For any major edit (more than 15
+lines, or so, in aggregate per person), you need to make a copyright
+assignment to the Free Software Foundation. This is necessary as the
+FSF must at all times be in a position to enforce the GNU General
+Public License.
+
+Here’s the process:
+
+@enumerate
+@item
+Review and adapt the request form below.
+@item
+Email the specified address with your request.
+@item
+Await a legal agreement from the FSF@.
+@item
+Sign and return the document, which can be done via email.
+@end enumerate
+
+The entire process usually takes about a week and needs to be
+completed only once, allowing you to contribute to GNU Emacs.
+
+@example
+Please email the following information to assign@@gnu.org, and we
+will send you the assignment form for your past and future changes.
+
+Please use your full legal name (in ASCII characters) as the subject
+line of the message.
+
+REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES
+
+[Additional people we should notify about the progress of the assignment.]
+
+Thanos Apollo <public@@thanosapollo.org>
+
+[What is the name of the program or package you're contributing to?]
+
+Emacs
+
+[Did you copy any files or text written by someone else in these changes?
+Even if that material is free software, we need to know about it.]
+
+
+[Do you have an employer who might have a basis to claim to own
+your changes? Do you attend a school which might make such a claim?]
+
+
+[For the copyright registration, what country are you a citizen of?]
+
+
+[What year were you born?]
+
+
+[Please write your email address here.]
+
+
+[Please write your postal address here.]
+
+
+[Which files have you changed so far, and which new files have you written
+so far?]
+
+@end example
+
+@bye
