nobiot / zero-to-emacs-and-org-roam

Step by step guide from zero to installing and setting up Emacs and Org-roam on Windows 10

Notes on Org-roam V2

As of 17 Jul 2021, V2 has been released. Both MELPA and MELPA-Stable have this version of Org-roam. It will be markedly different from v1 for both its initial setup and daily usage. At the moment, most of the content of guide will only be applicable to v1 for Org-roam and its related packages such as Org-roam-bibtex.

I am gradually revising this guide in its entirety for v2.

So far the following chapters have been updated:

1. Get Emacs for Windows
2. Use Emacs to write some text (including copy & paste)
3. Improve quality-of-life with your font, theme, and minimal select packages
4. Set up Org-roam (including MSYS2 and emacsql-sqlite.exe) [WIP but main parts are illustrated with a series of screen shots, so you should be able to install Org-roam V2]

The the latest version of this guide compatible for v1 is available in the v1 branch of this repositry.

Zero to Emacs and Org-roam: a step-by-step guide on Windows 10

I took the liberty of creating a step-by-step guide for people new to Emacs. I have written this with Windows users with no Linux or programming background in mind, zero about Emacs.

The guide aims to get you going real quick, starting with downloading Emacs with vanilla configuration (no Doom, no Spacemacs).

I won't repeat why you might like to use Emacs or plain text to write. Here is what I think is the best response to the question: "The Plain Person’s Guide to Plain Text Social Science" by Kieran Healy of Duke University.

At the end of step-by-step guide of Part 1, your Emacs will look like this.

[ Image to be inserted after writing up Part 1]

Audience and purpose in mind

The audience I have had in mind are:

• New to Emacs
• Windows users (Emacs part should be useful for others, I hope)
• No programming or Linux background
• Looking to use Org-roam / Emacs to help write long-form material (essays / papers about life, humanities, or some qualitative social sciences, etc.) as opposed to math and programming

Even if you are already down the path of using a framework like Doom, I hope stepping back a little and actually finishing configuration from scratch will help you understand how things fit together – it’s a bit like DIY making stuff; completing one thing from start to finish seems to help you leap to the next level of understanding and confidence for some reason.

Part 1

1. Get Emacs for Windows
2. Use Emacs to write some text (including copy & paste)
3. Improve quality-of-life with your font, theme, and minimal select packages
4. Set up Org-roam (including MSYS2 and emacsql-sqlite.exe) [WIP but main parts are illustrated with a series of screen shots]

Part 2

5. (maybe) How to swap CapsLock with Ctrl
6. Set up Org-roam-ui for a graph visualization of your notes
7. Set up Org-ref and Org-roam-bibtex (ORB)
8. Export to MS Word
9. Set up a spell checker (Hunspell, including how to get it)

Part 3

10. Work with PDF files in Emacs with PDF-Tools, Org-noter, and ORB
11. Insert an image from the clipboard, or the Snipping Tool on Windows (incl. in-line display resizing without Imagemagick, or external programs)

License

This work is licensed under a CC BY-SA 4.0 license, except for source code and documentation excerpts from Emacs and Org-roam project.

zero-to-emacs-and-org-roam's Issues

Possible source for the clipboard image insertion

I've also been using a similar process for inserting clipboard images into org files, and this is where I found it.
https://www.sastibe.de/2018/11/take-screenshots-straight-into-org-files-in-emacs-on-win10/
Might have been the same place you also came across it.
(Hope this isn't rude or anything. This is the first github issue I have raised.)

hunspell binary install via choco

It seems you can use chocolatey to install hunspell easily.

PS C:\Windows\system32> choco search hunspell
Chocolatey v0.10.15
hunspell.portable 1.7.0 [Approved] Downloads cached for licensed users
1 packages found.
PS C:\Windows\system32> choco install hunspell.portable
Chocolatey v0.10.15
Installing the following packages:
hunspell.portable
By installing you accept licenses for the packages.
Progress: Downloading hunspell.portable 1.7.0... 100%

hunspell.portable v1.7.0 [Approved]
hunspell.portable package files install completed. Performing other installation steps.
The package hunspell.portable wants to run 'chocolateyInstall.ps1'.
Note: If you don't run this script, the installation will fail.
Note: To confirm automatically next time, use '-y' or consider:
choco feature enable -n allowGlobalConfirmation
Do you want to run the script?([Y]es/[A]ll - yes to all/[N]o/[P]rint): Y

Downloading hunspell.portable
  from 'https://github.com/mlt/hunspell/releases/download/appveyor_v1.7.0/hunspell-msvc-Release-x64.zip'
Progress: 100% - Completed download of C:\Users\rnwol\AppData\Local\Temp\chocolatey\hunspell.portable\1.7.0\hunspell-msvc-Release-x64.zip (4.33 MB).
Download of hunspell-msvc-Release-x64.zip (4.33 MB) completed.
Extracting C:\Users\rnwol\AppData\Local\Temp\chocolatey\hunspell.portable\1.7.0\hunspell-msvc-Release-x64.zip to C:\ProgramData\chocolatey\lib\hunspell.portable\tools...
C:\ProgramData\chocolatey\lib\hunspell.portable\tools
 ShimGen has successfully created a shim for hunspell.exe
 ShimGen has successfully created a shim for testparser.exe
 The install of hunspell.portable was successful.
  Software installed to 'C:\ProgramData\chocolatey\lib\hunspell.portable\tools'

Chocolatey installed 1/1 packages.
 See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).

This will add hunspell.exe to the path.

PS C:\Windows\system32> C:\ProgramData\chocolatey\bin\hunspell.exe --version
@(#) International Ispell Version 3.2.06 (but really Hunspell 1.7.0)


Copyright (C) 2002-2014 László Németh. License: MPL/GPL/LGPL.

Based on OpenOffice.org's Myspell library.
Myspell's copyright (C) Kevin Hendricks, 2001-2002, License: BSD.

This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE,
to the extent permitted by law.

Failure to install, "Symbol's function definition is void: org-roam-mode"

Hello!
I tried to follow the instructions to install org-roam on Windows. I started with a clean Emacs installation, added Melpa, org, and org-roam. Downloaded the sqlite executables and verified they run from the command line.

When Emacs starts, I get Symbol's function definition is void: org-roam-mode.

I uninstalled and then re-installed -- messages show:

Could not find C compiler, skipping SQLite build
Org-roam initialization: (error "No EmacSQL SQLite binary available, aborting")
Operation [ Install 1 ] finished

The docs suggest that this step isn't necessary if I make the sqlite executables available (by adding it to exec-path).

So I'm not sure if I'm doing something wrong -- I tried specifying the path as c:/dev/bin, which is a directory that contains sqlite3.exe, etc., but also with the slashes the other way, and suffixed with a slash.

Thanks so much!

Part 3: Swap Caps and Control via PowerToys

Swapping caps and control can be done with the keyboard manager from the official Microsoft project PowerToys. Included is the KeyboardManager which allows the mapping of CapsLock to Control (among other things). It includes other utilities, but all are disabled by default. I personally use it specifically for this reason.

30.Set-up-Org-roam.md - Reference to M-h e

In the section Set-up Org-roam, there is this line:

Now you can save this. Let's quit Emacs and relaunch it. Once you see the start screen, invoke M-h e to view "echo message." Do you notice the two files and one link you created earlier have been added to Org-roam's database?

By default, M-h is bound to mark-paragraph, so "M-h e" just types 'e' into the active buffer.

Another custom configuration I've missed, perhaps?

It seems Firefox with old version of org also require the patch for org-protocol

Runing Msys2 version of Emacs 26.3 Org version 9.19, and Firefox 79.0, clicking on the org-roam graph will throw up a blank file.

The patch for Chrome (https://github.com/nobiot/Zero-to-Emacs-and-Org-roam/blob/main/90.org-protocol.md#chrome-only-patch-org-mode-for-org-protocol-and-org-roam-protocol) can solve this issue.

Consider installing `clang` instead of `msys2`

Zero-to-Emacs-and-Org-roam/30.setup-org-roam.md

Lines 5 to 20 in 3dce488

	## Install MSYS2
	
	
	Run MSYS2 after installation completes.
	
	You can simply install `gcc` by typing:
	pacman -S gcc
	
	You could update the package repository as instructed in the documentaion; you can do it but you don't have to.

In Windows 11, at least, the following worked for me (and feels a little less involved than MSYS2). From admin CMD prompt:

1. winget install LLVM.LLVM
2. set PATH=%PATH%;%PROGRAMFILES%\LLVM\bin
3. (optional) where clang to verify clang is available
4. run emacs from this prompt and proceed to "Install Org-roam in Emacs" phase -- emacsql-sqlite should compile fine...

Windows 11: No EmacSQL SQLite binary available, aborting

Roam is a very promising tool and I have followed the instructions to set up org roam on Windows. However, it still doesn't work. When I "C-c n l" to open a new org file, it just says "No EmacSQL SQLite binary available, aborting".

I did install gcc through msys64 and install sqlite3 and put them in the path. Any insights will be helpful if I should go to modify the roam .el file.

org-roam-find-file doesn't show contents of roam directory

In your next-to-final step after restarting Emacs

Invoke org-roam-find-file by typing C-c n /, and then press TAB to let Emacs list the titles of your files...

I am not shown the contents of my roam directory, just a blank mini-buffer. But if I invoke org-roam-find-directory I do get my roam directory where the two files new-file.org and second-file.org. I can chose these, and then, yes, org-roam seems to know about them, i.e., I invoke the backlink buffer and see that my two files created in the previous guide are noted.

Also, in this guide you don't establish a roam directory, i.e., (org-roam-directory "~/Dropbox/org/roam/")

This is my init based on what you say here and the main org-roam readme Installation section

(use-package org-roam
  :ensure t
  :hook
  (after-init . org-roam-mode)
  :custom
  (org-roam-directory "~/Dropbox/org/roam/")
  :bind (:map org-roam-mode-map
              (("C-c n l" . org-roam)
               ("C-c n f" . org-roam-find-file)
               ("C-c n g" . org-roam-graph))
              :map org-mode-map
              (("C-c n i" . org-roam-insert))
              (("C-c n I" . org-roam-insert-immediate))))

(global-set-key (kbd "C-c n r") #'org-roam-buffer-toggle-display)
(global-set-key (kbd "C-c n b") #'org-roam-switch-to-buffer)
(global-set-key (kbd "C-c n d") #'org-roam-find-directory)
(global-set-key (kbd "C-c n c") #'org-roam-db-build-cache)

(require 'company-org-roam)
(push 'company-org-roam company-backends)

Disclaimer: I didn't start this guide with emacs -Q, rather, my existing Emacs/org-mode config.

Dead link to gif in Part 1.4 (animation to find font name)

Hi, the link to the gif in Part 1.4 at the end of the "Set your font" section no longer exists (https://github.com/nobiot/Zero-to-Emacs-and-Org-roam/blob/main/images/2020-06-16_18-16-01.gif)

404 link: Set a variable within Emacs

Under the heading:
https://github.com/nobiot/Zero-to-Emacs-and-Org-roam/blob/main/30.Set-up-Org-roam.md#install-sqlite

Below the second image.

The second list item:

Set a variable within Emacs

is a link to:
https://org-roam.github.io/org-roam/manual/Post_002dInstallation-Tasks

Clicking on the link, opens a page that says:

404
File not found