branch: externals/org-mem
commit 343a4022aae985a1c9c8e35e71fa4b4798a2d120
Author: Martin Edström <[email protected]>
Commit: Martin Edström <[email protected]>
Docs
---
README.org | 27 +++++++++++++++++++++++++--
org-mem.texi | 33 +++++++++++++++++++++++++++++++--
2 files changed, 56 insertions(+), 4 deletions(-)
diff --git a/README.org b/README.org
index b1652ee7f0..3231bd2ab4 100644
--- a/README.org
+++ b/README.org
@@ -121,7 +121,7 @@ Now, you have a new, all-fake org-roam.db! Test that
org-roam's =org-roam-db-qu
(org-roam-db-query [:select * :from files :limit 10])
#+end_src
-If it works, then various packages that depend on org-roam's DB should also
work without issue.
+If it works, then various packages that depend on org-roam's DB should also
work without issue. However, you'll have to be content with them pulling in
org-roam even if you never turn it on.
N/B: because =(equal (org-roam-db) (org-mem-roamy-db))=, the above is
equivalent to these expressions:
@@ -130,7 +130,30 @@ N/B: because =(equal (org-roam-db) (org-mem-roamy-db))=,
the above is equivalent
(emacsql (org-mem-roamy-db) [:select * :from files :limit 10])
#+end_src
-A known issue when when you run multiple Emacs instances: "attempt to write a
readonly database". Get unstuck with =M-: (org-roam-db--close-all)=.
+*** To developers
+
+If you write a package that actually only needed to use org-roam's DB and not
its other utilities like =org-roam-capture=, you should be able to stop
requiring org-roam, and do e.g.
+
+#+begin_src elisp
+(defun my-db ()
+ (cond ((fboundp 'org-roam-db) (org-roam-db))
+ ((fboundp 'org-mem-roamy-db) (org-mem-roamy-db))
+ (t (error "Enable either org-roam-db-autosync-mode or
org-mem-roamy-db-mode"))
+#+end_src
+
+and then rewrite all your =(org-roam-db-query ...)= forms to:
+
+#+BEGIN_SRC elisp
+(emacsql (my-db) ...)
+#+END_SRC
+
+In theory, anyway ;-)
+
+Please report any issues!
+
+*** Known issue
+
+Error "attempt to write a readonly database" can happen when when you run
multiple Emacs instances. Get unstuck with =M-: (org-roam-db--close-all)=.
*** View what info is in the DB
diff --git a/org-mem.texi b/org-mem.texi
index d044c48534..fafbcea7a5 100644
--- a/org-mem.texi
+++ b/org-mem.texi
@@ -61,6 +61,8 @@ A SQLite database@comma{} for free
* Without org-roam installed::
* With org-roam installed::
+* To developers::
+* Known issue::
* View what info is in the DB::
Elisp API
@@ -168,6 +170,8 @@ In the future we may also create something that fits
@uref{https://github.com/nd
@menu
* Without org-roam installed::
* With org-roam installed::
+* To developers::
+* Known issue::
* View what info is in the DB::
@end menu
@@ -203,7 +207,7 @@ Now@comma{} you have a new@comma{} all-fake org-roam.db!
Test that org-roam's @
(org-roam-db-query [:select * :from files :limit 10])
@end lisp
-If it works@comma{} then various packages that depend on org-roam's DB should
also work without issue.
+If it works@comma{} then various packages that depend on org-roam's DB should
also work without issue. However@comma{} you'll have to be content with them
pulling in org-roam even if you never turn it on.
N/B: because @samp{(equal (org-roam-db) (org-mem-roamy-db))}@comma{} the above
is equivalent to these expressions:
@@ -212,7 +216,32 @@ N/B: because @samp{(equal (org-roam-db)
(org-mem-roamy-db))}@comma{} the above i
(emacsql (org-mem-roamy-db) [:select * :from files :limit 10])
@end lisp
-A known issue when when you run multiple Emacs instances: "attempt to write a
readonly database". Get unstuck with @samp{M-: (org-roam-db--close-all)}.
+@node To developers
+@section To developers
+
+If you write a package that actually only needed to use org-roam's DB and not
its other utilities like @samp{org-roam-capture}@comma{} you should be able to
stop requiring org-roam@comma{} and do e.g.
+
+@lisp
+(defun my-db ()
+ (cond ((fboundp 'org-roam-db) (org-roam-db))
+ ((fboundp 'org-mem-roamy-db) (org-mem-roamy-db))
+ (t (error "Enable either org-roam-db-autosync-mode or
org-mem-roamy-db-mode"))
+@end lisp
+
+and then rewrite all your @samp{(org-roam-db-query ...)} forms to:
+
+@lisp
+(emacsql (my-db) ...)
+@end lisp
+
+In theory@comma{} anyway ;-)
+
+Please report any issues!
+
+@node Known issue
+@section Known issue
+
+Error "attempt to write a readonly database" can happen when when you run
multiple Emacs instances. Get unstuck with @samp{M-: (org-roam-db--close-all)}.
@node View what info is in the DB
@section View what info is in the DB
