(doc): Add section for C Compiler (#1593)

* (doc): Add section for C Compiler

In the Post-Installation Tasks section, I suggest to add a sub-section for the C
compiler requirement for emacsql-sqlite. I have put an explanation for Windows
-- I have tried to make it as succinct as I can without losing some fine points
that I believe important for users to avoid confusion.

I have just removed MSYS2 and the PATH on my Windows machine and repeated the
process as I described it here to confirm that it works.

Since this new part is distinct from the existing paragraphs for SQLite, I also
suggest a sub-section heading for them -- I used "SQLite" as its title.

Please feel feel to change any part as you see fit.

It might be also useful if macOS users added their parts. I believe XCode is the
easiest way to install a C compiler (I believe it would be clang for recent
XCode versions) or perhaps brew. I don't use macOS so I will refrain from adding
this part..

I did not add .texi file to this commit -- last time, I believe you had to
revise the texi file that my machine generated anyway. Let me know if I should
follow up with a texi file.

* remove reference to emacsql-sqlite3

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>

doc/org-roam.org

@@ -198,8 +198,6 @@ using:
   M-x package-install RET org-roam RET
 #+END_EXAMPLE
 
-Now see [[*Post-Installation Tasks][Post-Installation Tasks]].
-
 ** Installing from Apt
 
 Users of Debian 11 or later or Ubuntu 20.10 or later can simply install Org-roam
@@ -248,7 +246,7 @@ dependencies that it requires. These include:
 - s
 - org
 - emacsql
-- emacsql-sqlite3
+- emacsql-sqlite
 
 You can install this manually as well, or get the latest version from MELPA. You
 may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]] to help manage this.
@@ -291,23 +289,43 @@ file:
 install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
 #+end_src
 
-** Post-Installation Tasks
+** Installation Troubleshooting
+*** C Compiler
+Org-roam relies on an Emacs package called ~emacsql~ and ~emacsql-sqlite~ to
+work with the ~sqlite~ database. Both of them should be installed automatically
+in your Emacs environment as a prerequisite for Org-roam when you install it.
 
-Org-roam requires ~sqlite3~ to be locatable by Emacs (i.e. on ~exec-path~).
+~emacsql-sqlite~ requires a C compiler (e.g. ~gcc~ or ~clang~) to be present in
-Please ensure that ~sqlite3~ is installed appropriately on your operating
+your computer. How to install a C compiler depends on the OS that you use.
-system. You can verify that this is the case by executing [fn:2]:
 
-#+BEGIN_SRC emacs-lisp
+- For Windows:
-  (executable-find "sqlite3")
-#+END_SRC
 
-If you have ~sqlite3~ installed, and ~executable-find~ still reports ~nil~, then
+There are various ways to install one, depending on how you have installed
-the path to the executable is not a member of the Emacs variable ~exec-path~.
+Emacs. If you use Emacs within a Cygwin or MinGW environment, then you should
-Rectify this by manually adding the path within your Emacs configuration:
+install a compiler using their respective package manager.
 
-#+BEGIN_SRC emacs-lisp
+If you have installed your Emacs from the [[https://www.gnu.org/software/emacs/][GNU Emacs website]], then the easiest way
-  (add-to-list 'exec-path "path/to/sqlite3")
+is to use [[https://www.msys2.org/][MSYS2]] as at the time of this writing:
-#+END_SRC
+
+1. Use the installer in the official website and install MSYS2
+2. Run MSYS2
+3. In the command-line tool, type the following and answer "Y" to proceed:
+   
+   #+BEGIN_SRC bash
+     pacman -S gcc
+   #+END_SRC
+
+   Note that you do not need to manually set the PATH for MSYS2; the
+installer automatically takes care of it for you.
+
+4. Open Emacs and call ~M-x org-roam-setup~
+
+   This will automatically start compiling ~emacsql-sqlite~; you should see a
+message in minibuffer. It may take a while until compilation completes. Once
+complete, you should see a new file ~emacsql-sqlite.exe~ created in a subfolder
+named ~sqlite~ under ~emacsql-sqlite~ installation folder. It's typically in
+your Emacs configuration folder like this:
+~/.config/emacs/elpa/emacsql-sqlite-20190727.1710/sqlite~
 
 * Getting Started
 ** The Org-roam Node

doc/org-roam.texi

@@ -94,7 +94,11 @@ Installation
 * Installing from MELPA::
 * Installing from Apt::
 * Installing from Source::
-* Post-Installation Tasks::
+* Installation Troubleshooting::
+
+Installation Troubleshooting
+
+* C Compiler::
 
 Getting Started
 
@@ -335,7 +339,7 @@ development repository.
 * Installing from MELPA::
 * Installing from Apt::
 * Installing from Source::
-* Post-Installation Tasks::
+* Installation Troubleshooting::
 @end menu
 
 @node Installing from MELPA
@@ -389,8 +393,6 @@ using:
 M-x package-install RET org-roam RET
 @end example
 
-Now see @ref{Post-Installation Tasks}.
-
 @node Installing from Apt
 @section Installing from Apt
 
@@ -453,7 +455,7 @@ org
 emacsql
 
 @item
-emacsql-sqlite3
+emacsql-sqlite
 @end itemize
 
 You can install this manually as well, or get the latest version from MELPA@. You
@@ -504,26 +506,64 @@ file:
 install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
 @end example
 
-@node Post-Installation Tasks
+@node Installation Troubleshooting
-@section Post-Installation Tasks
+@section Installation Troubleshooting
 
-Org-roam requires @code{sqlite3} to be locatable by Emacs (i.e. on @code{exec-path}).
+@menu
-Please ensure that @code{sqlite3} is installed appropriately on your operating
+* C Compiler::
-system. You can verify that this is the case by executing @footnote{Two easy ways to evaluate elisp: 1) Place the cursor after the closing
+@end menu
-paren and run @samp{M-x eval-last-sexp RET} or 2) Press @samp{C-c C-c} with your cursor in
-an Org file code block (like @samp{#+BEGIN_SRC emacs-lisp}).}:
 
-@lisp
+@node C Compiler
-(executable-find "sqlite3")
+@subsection C Compiler
-@end lisp
 
-If you have @code{sqlite3} installed, and @code{executable-find} still reports @code{nil}, then
+Org-roam relies on an Emacs package called @code{emacsql} and @code{emacsql-sqlite} to
-the path to the executable is not a member of the Emacs variable @code{exec-path}.
+work with the @code{sqlite} database. Both of them should be installed automatically
-Rectify this by manually adding the path within your Emacs configuration:
+in your Emacs environment as a prerequisite for Org-roam when you install it.
 
-@lisp
+@code{emacsql-sqlite} requires a C compiler (e.g. @code{gcc} or @code{clang}) to be present in
-(add-to-list 'exec-path "path/to/sqlite3")
+your computer. How to install a C compiler depends on the OS that you use.
-@end lisp
+
+@itemize
+@item
+For Windows:
+@end itemize
+
+There are various ways to install one, depending on how you have installed
+Emacs. If you use Emacs within a Cygwin or MinGW environment, then you should
+install a compiler using their respective package manager.
+
+If you have installed your Emacs from the @uref{https://www.gnu.org/software/emacs/, GNU Emacs website}, then the easiest way
+is to use @uref{https://www.msys2.org/, MSYS2} as at the time of this writing:
+
+@itemize
+@item
+Use the installer in the official website and install MSYS2
+
+@item
+Run MSYS2
+
+@item
+In the command-line tool, type the following and answer ``Y'' to proceed:
+
+@example
+pacman -S gcc
+@end example
+
+Note that you do not need to manually set the PATH for MSYS2; the
+@end itemize
+installer automatically takes care of it for you.
+
+@itemize
+@item
+Open Emacs and call @code{M-x org-roam-setup}
+
+This will automatically start compiling @code{emacsql-sqlite}; you should see a
+@end itemize
+message in minibuffer. It may take a while until compilation completes. Once
+complete, you should see a new file @code{emacsql-sqlite.exe} created in a subfolder
+named @code{sqlite} under @code{emacsql-sqlite} installation folder. It's typically in
+your Emacs configuration folder like this:
+@code{/.config/emacs/elpa/emacsql-sqlite-20190727.1710/sqlite}
 
 @node Getting Started
 @chapter Getting Started