Installing the software for CSCI 054

Open up your computer's terminal and navigate to your downloaded setup folder. On Mac OS, you can type cd and then space and drag this folder into the Terminal window, then hit return. Now run mkdir -p ~/.emacs.d ; mv init.el ~/.emacs.d ; rm -f ~/.emacs to put the course emacs configuration into your home directory and erase any old emacs initialization that might be hanging around. At this point you can launch Emacs by finding and double-clicking its icon. The Emacs window you see should post a bunch of messages and eventually (once it settles down) it shouldn't have any toolbar icons, so if it does—or if you see a window describing some errors (not warnings, those are fine)—please talk to Prof. Osborn.

You're in the situation where we want Emacs to be able to find the coqtop program inside of the CoqIDE application's package. You'll want to add these lines to your .emacs.d/init.el using a text editor (perhaps emacs; glance down at the "For Everybody" section for a crash course in editing with emacs):

(add-to-list 'exec-path "/Applications/CoqIDE_8.10.2.app/Contents/Resources/bin")
(setenv "PATH" (concat "/Applications/CoqIDE_8.10.2.app/Contents/Resources/bin:" (getenv "PATH")))
(setq coq-prog-name "/Applications/CoqIDE_8.10.2.app/Contents/Resources/bin/coqtop")
;;; and the same kind of thing for latex:
(add-to-list 'exec-path "/Library/TeX/texbin")
(setenv "PATH" (concat "/Library/TeX/texbin:" (getenv "PATH")))

Add them before the (require 'proof-general) line. If you're in emacs, you can use M-x and choose eval-buffer and you won't need to restart emacs or reopen Basics.v.

If you are using iCloud Drive: iCloud Drive puts folders in weird places and makes it hard for emacs to get to them. I suggest making your cs54 directory directly inside of your home directory, which you can get to in Finder by pressing command-shift-h.

After unzipping the Emacs distribution to a place you like, find the bin\runemacs.exe script and make a new shortcut to it on the desktop or your start menu or wherever you prefer. Next, open your file browser and navigate to this folder (the one this README file is in). This folder also contains a folder called .emacs.d which might be a hidden folder (if it is, follow the instructions on Microsoft's website to show hidden folders for now). Copy this folder to where Emacs expects to find it, which is by default C:\Users\yourusername\AppData\Roaming. Then open up your Emacs shortcut and stuff should start happening, in particular some messages about installing and compiling packages printed at the bottom of the Emacs window, and you should eventually see an Emacs window with no toolbar icons or anything. If anything goes wrong or if you see a window talking about some errors (not warnings, those are fine), talk to Prof. Osborn.

Before you proceed, open up ~/.emacs.d/init.el in Emacs (you can use C-x C-f, delete the whole line, and type in ~/.emacs.d/init.el and hit return) and modify the commented-out line 29. Make sure that the string value for coq-prog-name starts with the path to where you installed Coq, and delete the comment characters (;;;). You'll also likely need to add lines like these (double check that Coq and TeXLive's bin folder, which should have pdflatex in it, are where this code thinks it is):

(add-to-list 'exec-path "c:/Coq/bin")
(setenv "PATH" (concat "c:/Coq/bin;" (getenv "PATH")))
;;; and the same kind of thing for latex:
(add-to-list 'exec-path "c:/TeXLive/2019/bin")
(setenv "PATH" (concat "c:/TeXLive/2019/bin;" (getenv "PATH")))

Now restart emacs.

At this point you have a working Emacs! Test it out by opening Basics.v:

1. If you've never used Emacs before, click the Emacs Tutorial link on the splash page for a crash course (despite what it says, you can also use arrow keys to move the cursor around). I have modified some keybindings (e.g. to put undo on control-z) so also make a mental note to look through the .emacs.d/init.el file to see what's included.
2. Hit control and x at the same time (C-x)
3. Hit control and f at the same time (C-f)
4. You should see a textual file browser at this point with some headers. If you don't, Emacs might have a different opinion about which key is control than the labels on your keyboard. Hit ESC ESC ESC (the "get me out of here" keyboard sequence) and try again with a different key (maybe Alt or Command or…). Once you find out which key is control, C-g ("control g") is your "cancel the current thing that's happening" command. I use it all the time.
5. Once you see the file browser (a feature of a plugin I've included called Helm), you can use it like so (try finding Basics.v)
   • Left arrow and right arrow to go up higher/down deeper in the folder hierarchy; up and down to browse the list
   • Type a few letters to fuzzy search for a folder or file name (then hit right to go inside it)
   • Hit return to open ("find" or "visit" in emacs-ese) the file

I think Helm is really helpful for making Emacs more discoverable, so I've included and configured it. If you want to ask Emacs what it can do, type M-x ("Meta x"; meta key might be Alt or Command or…) and then type a few letters to search through its commands. You could hit C-j over any of those to view its documentation. Anyway, hit C-g to get out of that command search and type C-h v (C-h followed by v) and type a few letters (e.g. line num) and hit return. You can toggle the display of line numbers temporarily by clicking Toggle or permanently by clicking Customize. From the Customize interface you can change variable values, save them for future sessions, and search for all kinds of customization options (or navigate a tree of them).

If you want to change your default font, Emacs calls those "faces"; you can find out which face is being used to render a given bit of text by issuing M-x describe-face and hitting return. From there you can follow links to customize the face. A good one to customize is default-face (you could also find it by M-x customize-apropos-faces RET default). You may want to change a lot of faces or other visual settings at once, but for that I'll direct you to Emacs themes which you can activate via M-x load-theme and install new ones using M-x package-list-packages and searching for themes (C-s is bound to helm-swoop, a package which finds occurrences of strings in the current buffer; navigate up and down with arrow keys and hit return when you're done). Click the package name and then find the Install button in the window that opens up, or do e.g. M-x package-install RET leuven-theme or M-x package-install RET moe-theme. You can also tweak the "mode line" (the line of text at the bottom of each window); some packages for this are spaceline and doom-modeline. The theme I use is doom-nord-light (part of doom-themes) and my modeline is a slightly customized doom-modeline.

Go ahead and find a text buffer (e.g., this file). To make a selection (to "mark" the "region"), you could drag with your mouse (old and busted) or hit C-SPACE to mark one end of the region and activate the region, and then move the cursor around to move the other end of it; to act on the selection, just hit delete or type or C-w ("kill", i.e. cut) then C-y ("yank", i.e. "paste"). Kill is slightly different from cut (killing in succession will extend the killed text rather than replacing it) and kill also puts entries into a "kill-ring" which you can view and search with M-y (helm-show-kill-ring). Some more indispensable movement keys include C-a (beginning of line), C-e (end of line), and M-DEL (meta-backspace) and M-d to kill the rest of the word before or after the point (cursor) respectively.

You may have noticed Emacs has different words for some things (point instead of cursor; region instead of selection; buffer, window, frame instead of file, pane, window; find- or visit- instead of open; kill and yank instead of cut and paste); this is because Emacs predates the common names for those things and its developers had to come up with its own names. Another difference like this concerns undo. I wrote before that I have bound C-z to undo, which is true. But I haven't bound anything to redo. Why? Because there's no such thing as redo in Emacs. Instead, you undo your act of undoing. While this seems absurd at first, it has the advantage that no edit is ever lost (you don't have the problem of undoing a bunch and then modifying the text and losing the ability to redo back to where you were). It's also pretty usable if you remember this heuristic:

• To undo a series of changes, keep hitting C-z.
• If you want to switch directions and start redoing, perform some other action (e.g. C-g) and then hit C-z again. This will start undoing the undos you did before.
• Hit C-g again to undo your undoing of the undos (i.e., to switch directions back again).

You'll get the hang of it in no time!

I've set up this init file to automatically install Proof General and company-coq, which help with the business of writing Coq programs and proofs. I recommend reading their manuals when you get a chance. Emacs is so-called "self documenting", not only because it includes manuals (C-h i) but also because of the help menu items available starting with C-h with which you can learn about emacs's built-in functions, variables, and other features.

Finally, I want you to treat your Emacs as yours. This, if anything, is the key benefit of using Emacs: it belongs to you and you can change it however you want. Feel free to use customize or to modify the .emacs.d/init.el file to add other packages, configure things how you like it, make it more livable for you. Virtually everything in the program is tweakable or reprogrammable and it's up to you to make the most of that. For example, by default to jump to a specific line of a file you would use M-g g; I not only think M-g by itself is better, but there's an alternative called avy for jumping around a file and I use its avy-goto-line function instead (M-x package-install RET avy and bind avy-goto-line to M-g using global-set-key). I also do a lot of file browsing in Emacs's built-in browser dired, so I bind C-x j to dired-jump. I rarely leave Emacs, so I rebound C-x C-c (quit emacs) to a function I defined which asks me whether I really want to quit before saving all files and quitting. You'll find your own special tweaks and customizations as you use the program more.