From 15c1a46e41defa2c907665399cd81467800c3d74 Mon Sep 17 00:00:00 2001
From: Noboru Ota <me@nobiot.com>
Date: Wed, 28 Apr 2021 07:43:42 +0200
Subject: [PATCH] (doc): Add file-truename to set org-roam-directory (README
 and documentation) (#1487)

* (doc): Add file-truename to set org-roam-directory

Refer this debuging Slack exchange:
https://orgroam.slack.com/archives/CV160S8EL/p1619089118195300

Not using `file-truename` to set
`org-roam-directory` can lead to an issue that is
hard to identify.

It appears that cache database may updates with
files but `org-roam-buffer` fails to find the file
as symbolic links do not resolve. This is
confusing as the table query to the table seems to
return what appears to be correct entries, but the
backlink fails to insert context around the
link (as Org-roam fails to find the file).

There have been similiar issues -- by making sure
`file-truename` is added in the documentation and
README, it is hoped to eliminate such issues to
recur.

This is probably relevant for V2.

* undo changes to texi

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
---
 README.md        | 5 ++++-
 doc/org-roam.org | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3d1f32c..4c5422c 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ Here's a sample configuration with `use-package`:
       :hook
       (after-init . org-roam-mode)
       :custom
-      (org-roam-directory "/path/to/org-files/")
+      (org-roam-directory (file-truename "/path/to/org-files/"))
       :bind (:map org-roam-mode-map
               (("C-c n l" . org-roam)
                ("C-c n f" . org-roam-find-file)
@@ -57,6 +57,9 @@ Here's a sample configuration with `use-package`:
               (("C-c n I" . org-roam-insert-immediate))))
 ```
 
+The `file-truename` function is only necessary when you use symbolic links
+inside `org-roam-directory`: Org-roam does not resolve symbolic links.
+
 Org-roam requires sqlite to function. Org-roam optionally uses Graphviz for
 graph-related functionality. It is recommended to install PCRE-enabled ripgrep
 for better performance and extended functionality.
diff --git a/doc/org-roam.org b/doc/org-roam.org
index 6b94b55..109abfa 100644
--- a/doc/org-roam.org
+++ b/doc/org-roam.org
@@ -331,9 +331,12 @@ create an empty directory, and set ~org-roam-directory~:
 
 #+BEGIN_SRC emacs-lisp
 (make-directory "~/org-roam")
-(setq org-roam-directory "~/org-roam")
+(setq org-roam-directory (file-truename "~/org-roam"))
 #+END_SRC
 
+The ~file-truename~ function is only necessary when you use symbolic links
+inside ~org-roam-directory~: Org-roam does not resolve symbolic links.
+
 We encourage using a flat hierarchy for storing notes, but some prefer using
 folders for storing specific kinds of notes (e.g. websites, papers). This is
 fine; Org-roam searches recursively within ~org-roam-directory~ for notes.