You know how I said last time Part 1 was just the introduction? I lied.

My emacs-settings.org file includes an introduction that covers what I already went over and more. I thought I’d skip it, but as I looked through the notes I left to myself — various guidelines, warnings, and tips — I realized that this is exactly the kind of stuff I should share.

Style

As I was writing this, I fell into a rabbit hole (of course) and made a couple of additional changes.

Style and style guides are important to me. In college, as an editor, I used the AP Stylebook as a bible almost, along with the Chicago Manual of Style for academic papers. When I worked as a technical writer, it was Microsoft’s stylebook I checked constantly — and some of it stuck (don’t say “click”; say “select”, don’t say “sign in”; say “log in,” etc.) The main point is to stick to a style and keep using it — which one matters less.

Here are the notes:

  1. Emacs keyboard shortcuts and file paths should be placed in verbatim (between = and =)1
  2. Code (as part of an explanation) should be placed in code (between and )

Code blocks: use structure templates (C-c C-,) and choose emacs-lisp from the list (this is defined below). It should be in lower case: #+begin_src emacs-lisp and #+end_src.

When explaining code: the explanation follows the code immediately (no space). Use a space after the code (new line) for the next item:

 explanation for item 1
 #+begin_src emacs-lisp
 code for item 1
 #+end_src
 
 explanation for item 2
 #+begin_src emacs-lisp
 code for item 2
 #+end_src

My settings file is long and requires that I jump around to different sections. As I was working on revamping it, I’ve learned quite a few useful “tricks” that I started sharing in earlier posts. These are always good to know, not just in our setting file.

Jump Back With the Mark Ring

While registers (I have a section about them below) are a nice org-mode feature I keep forgetting about, they’re a bit of an in-between too much or too little for most cases in this file. For quickly getting around, we should use the mark ring:

Use C-u C-SPC (built on set-mark-command) to jump back to where our marker was before, which is usually where we ended scrolling or moving to see something. Keep pressing to keep going back — it remembers all the positions we landed on. By default, it remembers the last 16 positions.

Editing Code Blocks

Edit code blocks with C-c ‘ instead of just working with the text inside the org buffer directly2

Don’t edit the text in a code block (#+begin_src… #+end_src) directly. While it works, we’re missing out on the power of org-edit-special, and this is one powerful org-mode feature. Here are some of the highlights relevant to me, in bold:

  *When at a table, call the formula editor with 'org-table-edit-formulas'.*
 When at table.el table, edit it in dedicated buffer.
 When in a source code block, call 'org-edit-src-code'; with prefix
   argument, switch to session buffer.
 When in an example block, call 'org-edit-src-code'.
 *When in an inline code block, call 'org-edit-inline-src-code'.* **(this is what we're doing here!)**
 When in a fixed-width region, call 'org-edit-fixed-width-region'.
 When in an export block, call 'org-edit-export-block'.
 When in a comment block, call 'org-edit-comment-block'.
 When in a LaTeX environment, call 'org-edit-latex-environment'.
 When at an INCLUDE, SETUPFILE or BIBLIOGRAPHY keyword, visit the included file.
 *When at a footnote reference, call 'org-edit-footnote-reference'.*
 When at a planning line call, 'org-deadline' and/or 'org-schedule'.
 When at an active timestamp, call 'org-timestamp'.

What it gives us when we work with the settings here:

  1. A separate temporary buffer, without the #+begin_src… #+end_src, which we can evaluate any time, without worrying about being at the end of an expression (parentheses) and use C-x C-e3.
  2. Safety net: as long as we don’t close it with another C-c ‘, it doesn’t save the code, and we can run it in that separate buffer to see what it does.

Also, nice bonus: it highlights the code we’re in with a separate color, and it will keep highlighting it as long as org-edit-special is open. Need a coffee refill? No problem, you know exactly where you left off.

In my config, I started using links more often instead of setting registers (as I noted earlier, registers are too much for moving around, but too little as permanent location savers). I stole the thunder from this section in this post, but it deserves its own post anyway. org-mode internal links are very powerful, and I don’t think the manual explains them well enough (examples would be good), so go check it out.

Registers

Registers can save a location in a file to be recalled later from anywhere else in Emacs, or, to save a chunk of code to be pasted (yanked) later.

  1. To save a location: C-x r SPC, then a number or a letter to name the register. So C-x r SPC and then 1 will save a register called “1” in the position the marker is on.
  2. To jump to a saved location in a register: C-x r j, then the number/letter we previously selected. So in this example, C-x r j and then 1 will take us back to the location we saved as “1”.
  3. To save a region in a register: First, highlight (select) a region in Emacs. Then C-x r s, then a number or a letter to name the register. So selecting this sentence, then C-x r s and then 1 will save the sentence in register 1.4
  4. To insert a saved region: C-x r i, then the number/letter we previously selected.
  5. To view saved registers: M-x view-register, which allows you to select one by number. A good replacement for C-x r j if you need a visual reminder like I do.

It’s a good idea to keep numbers for positions and letters for text so we don’t get them confused and overwrite our registers.

Footnotes

1 Most Emacs users, I believe, use code for file paths. The reason I have it different here is because I often talk about files in my posts without referring to code, and I will now make use of the <kbd></kbd> tags as well, which I forgot about. This is good for clarity, especially when we talk about Emacs, since Emacs and keyboard shortcuts are mentioned together all the time.

2 Those of you who code and write functions on Emacs regularly would probably find this “trick” trivial. However, as a person who does not have this background, I’ve been editing my code blocks directly in org for years — I had no idea org-edit-special exists. I’m sure some folks out there are in the same boat.

3 Which is, as I explained in my previous footnote, exactly what I’ve been doing for years. It works, but it can lead to mistakes, and it’s not as safe (you’re changing your settings, so if something goes wrong, Emacs’ startup will stop at the error).

4 In a usual discovery manner, I found out that C-x r + appends text to the register. So, if you were to select this footer here from the word “In” to the dot after “register”, you could then go to the word “So” and mark again to the word “footer” 7 words later, hit C-x r +, and then when you ready to yank (paste), hit C-x r i and both sections will be yanked as one. Actually, you could forgo C-x r i altogether and use C-x r + from the start, because if you append to an empty register, it will just append that first chunk.