Deploying to gh-pages from @ 5e42d854c1 🚀

manual.html

@@ -135,7 +135,13 @@ Installation
 </td></tr>
 <tr><td align="left" valign="top">&bull; <a href="#Installing-from-Source">Installing from Source</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 </td></tr>
-<tr><td align="left" valign="top">&bull; <a href="#Post_002dInstallation-Tasks">Post-Installation Tasks</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+<tr><td align="left" valign="top">&bull; <a href="#Installation-Troubleshooting">Installation Troubleshooting</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+
+Installation Troubleshooting
+
+</pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#C-Compiler">C Compiler</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 </td></tr>
 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 
@@ -452,7 +458,7 @@ development repository.
 </td></tr>
 <tr><td align="left" valign="top">&bull; <a href="#Installing-from-Source" accesskey="3">Installing from Source</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 </td></tr>
-<tr><td align="left" valign="top">&bull; <a href="#Post_002dInstallation-Tasks" accesskey="4">Post-Installation Tasks</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+<tr><td align="left" valign="top">&bull; <a href="#Installation-Troubleshooting" accesskey="4">Installation Troubleshooting</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 </td></tr>
 </table>
 
@@ -509,8 +515,6 @@ using:
 <pre class="example">M-x package-install RET org-roam RET
 </pre></div>
 
-<p>Now see <a href="#Post_002dInstallation-Tasks">Post-Installation Tasks</a>.
-</p>
 <hr>
 <span id="Installing-from-Apt"></span><div class="header">
 <p>
@@ -530,7 +534,7 @@ using Apt:
 <hr>
 <span id="Installing-from-Source"></span><div class="header">
 <p>
-Next: <a href="#Post_002dInstallation-Tasks" accesskey="n" rel="next">Post-Installation Tasks</a>, Previous: <a href="#Installing-from-Apt" accesskey="p" rel="prev">Installing from Apt</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> &nbsp; [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
+Next: <a href="#Installation-Troubleshooting" accesskey="n" rel="next">Installation Troubleshooting</a>, Previous: <a href="#Installing-from-Apt" accesskey="p" rel="prev">Installing from Apt</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> &nbsp; [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
 </div>
 <span id="Installing-from-Source-1"></span><h3 class="section">4.3 Installing from Source</h3>
 
@@ -575,7 +579,7 @@ dependencies that it requires. These include:
 
 </li><li> emacsql
 
-</li><li> emacsql-sqlite3
+</li><li> emacsql-sqlite
 </li></ul>
 
 <p>You can install this manually as well, or get the latest version from MELPA. You
@@ -624,28 +628,68 @@ file:
 </pre></div>
 
 <hr>
-<span id="Post_002dInstallation-Tasks"></span><div class="header">
+<span id="Installation-Troubleshooting"></span><div class="header">
 <p>
 Previous: <a href="#Installing-from-Source" accesskey="p" rel="prev">Installing from Source</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> &nbsp; [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
 </div>
-<span id="Post_002dInstallation-Tasks-1"></span><h3 class="section">4.4 Post-Installation Tasks</h3>
+<span id="Installation-Troubleshooting-1"></span><h3 class="section">4.4 Installation Troubleshooting</h3>
 
-<p>Org-roam requires <code>sqlite3</code> to be locatable by Emacs (i.e. on <code>exec-path</code>).
+<table class="menu" border="0" cellspacing="0">
-Please ensure that <code>sqlite3</code> is installed appropriately on your operating
+<tr><td align="left" valign="top">&bull; <a href="#C-Compiler" accesskey="1">C Compiler</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
-system. You can verify that this is the case by executing <a id="DOCF2" href="#FOOT2"><sup>2</sup></a>:
+</td></tr>
+</table>
+
+<hr>
+<span id="C-Compiler"></span><div class="header">
+<p>
+Up: <a href="#Installation-Troubleshooting" accesskey="u" rel="up">Installation Troubleshooting</a> &nbsp; [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="C-Compiler-1"></span><h4 class="subsection">4.4.1 C Compiler</h4>
+
+<p>Org-roam relies on an Emacs package called <code>emacsql</code> and <code>emacsql-sqlite</code> to
+work with the <code>sqlite</code> database. Both of them should be installed automatically
+in your Emacs environment as a prerequisite for Org-roam when you install it.
 </p>
-<div class="lisp">
+<p><code>emacsql-sqlite</code> requires a C compiler (e.g. <code>gcc</code> or <code>clang</code>) to be present in
-<pre class="lisp">(executable-find &quot;sqlite3&quot;)
+your computer. How to install a C compiler depends on the OS that you use.
+</p>
+<ul>
+<li> For Windows:
+</li></ul>
+
+<p>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.
+</p>
+<p>If you have installed your Emacs from the <a href="https://www.gnu.org/software/emacs/">GNU Emacs website</a>, then the easiest way
+is to use <a href="https://www.msys2.org/">MSYS2</a> as at the time of this writing:
+</p>
+<ul>
+<li> Use the installer in the official website and install MSYS2
+
+</li><li> Run MSYS2
+
+</li><li> In the command-line tool, type the following and answer &ldquo;Y&rdquo; to proceed:
+
+<div class="example">
+<pre class="example">pacman -S gcc
 </pre></div>
 
-<p>If you have <code>sqlite3</code> installed, and <code>executable-find</code> still reports <code>nil</code>, then
+<p>Note that you do not need to manually set the PATH for MSYS2; the
-the path to the executable is not a member of the Emacs variable <code>exec-path</code>.
+</p></li></ul>
-Rectify this by manually adding the path within your Emacs configuration:
+<p>installer automatically takes care of it for you.
 </p>
-<div class="lisp">
+<ul>
-<pre class="lisp">(add-to-list 'exec-path &quot;path/to/sqlite3&quot;)
+<li> Open Emacs and call <code>M-x org-roam-setup</code>
-</pre></div>
 
+<p>This will automatically start compiling <code>emacsql-sqlite</code>; you should see a
+</p></li></ul>
+<p>message in minibuffer. It may take a while until compilation completes. Once
+complete, you should see a new file <code>emacsql-sqlite.exe</code> created in a subfolder
+named <code>sqlite</code> under <code>emacsql-sqlite</code> installation folder. It&rsquo;s typically in
+your Emacs configuration folder like this:
+<code>/.config/emacs/elpa/emacsql-sqlite-20190727.1710/sqlite</code>
+</p>
 <hr>
 <span id="Getting-Started"></span><div class="header">
 <p>
@@ -2444,10 +2488,6 @@ Previous: <a href="#Function-Index" accesskey="p" rel="prev">Function Index</a>,
 
 <h5><a id="FOOT1" href="#DOCF1">(1)</a></h3>
 <p>To understand more about Roam, a collection of links are available in <a href="#Note_002dtaking-Workflows">Note-taking Workflows</a>.</p>
-<h5><a id="FOOT2" href="#DOCF2">(2)</a></h3>
-<p>Two easy ways to evaluate elisp: 1) Place the cursor after the closing
-paren and run &lsquo;<samp>M-x eval-last-sexp RET</samp>&rsquo; or 2) Press &lsquo;<samp>C-c C-c</samp>&rsquo; with your cursor in
-an Org file code block (like &lsquo;<samp>#+BEGIN_SRC emacs-lisp</samp>&rsquo;).</p>
 </div>
 <hr>
 

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

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