My EMACS How-To

I had started to use EMACS occasionally with version 20.7. Since 2016-11 I am using EMACS 25.1 and have been using it regularely. This folder contains documents where I share information about

how I use EMACS for software development for micro-controllers. Please see my notes below
how to create documentation using org-mode built into EMACS and org-mode's HTML export
how to integrate EMACS with Microsoft Windows.

The EMACS documentation, both built into EMACS and available online, is very complete and detailed. However I found myself jotting down things while I learned. I share these below. These might be useful to people who have similar requirements.

View

Using "EMACS Frames" Rather Than "EMACS Windows"

I appreciate EMACS supports well classical terminal operation by providing "windows" functionality. However I am using EMACS from a MS Windows desktop and I am used to working with native windows there, which are called "frames" in EMACS.

I have customised (download my init.el) EMACS such that it uses "frames" by default (for example when it opens a *help* window for you).

Zoom

C-x C-+ increase font site, repeat C-+ for more. Only affects current buffer

C-x C-- decrease font size

C-x C-0 go back to standard font size

Navigation

C-x r SPC r saves to cursor position in "register" r (one letter)

C-x r j r jumps back

Registers are volatile. Bookmarks are being saved.

Text-Alignment

In EMACS a paragraph is terminated by an empty line.

M-q "fill paragraph" aligns every line in a paragraph, breaking lines that are too long. The variable fill-column governs how long the lines are, the length defaults to 70 characters (more precisely: default right margin: 70).

However, to set the variable comment-auto-fill-only-comments to non-nil did not have the effect, to align automatically ;;; assembly language comments.

Modes I Use Often

Visualise Where a Search String Occurs in a Buffer

M-x occur

shows all lines in a buffer that contain the search string. They are shown in a separate frame/window, with hyperlinks you can follow/click. However, this works for one buffer only.

What M-x occur-mode does, I still need to understand.

Show a File in Hexadecimal and Edit

M-x hexl-mode

EMACS Serial Terminal Mode

Often I need a serial terminal app. to connect to a microcontroller via RS232 for debug purposes. As I use Windows, there is no out-of-the box app. ever since Hyperterm was not any more delivered with Windows. Fortunately such functionality is built into EMACS and can be activated via

M-x serial-terminal

See http://www.gnu.org/software/emacs/manual/html_node/emacs/Serial-Terminal.html

Search and Replace in Multiple Files

TAGS

Use TAGS

If you have a file open in a buffer (which sets the current directory) and then do

M-x tags-search

then EMACS tries to open a so called TAGS file in that directory. If the TAGS file is not in the same directory, then you could supply a relative or absolute path. Then EMACS asks you a search pattern.

M-,

looks for the next hit until all files have been processed.

Similarly

M-x tags-query-replace

does a query and replace.

To change the TAGS file that is being used, use

M-x visit-tags-table

The current directory can be changed in Menu, Files, Open Directory... . The path separator seems to be / even under Windows.

How to generate a TAGS file

To use the EMACS "TAGS" feature, you first got to generate a TAGS file specific to the project you are working. One possible procedure:

First generate a file with one line per file and give it a name, for example "flist.txt". It might look like:
src\DisplayC-1.asm
..\Common\portab.inc
..\Common\trUtil.inc
..\Common\trStdlib.inc
..\Common\trFIFO.inc
Then convert this file to a TAGS file. I do this using a script myGenTAGS.cmd

The script consists of two lines:

TYPE flist.txt | C:\Users\xyz\OneDrive\myPrograms\emacs-25.1\bin\etags.exe -
PAUSE

This will generate the file "TAGS" in the same directory. Replace the path above with the path where you installed EMACS (see my approach under Windows).

Setting Search Case Sensitivity

By default search regexp treats upper and lower case the same. This is set by the variable tags-case-fold-search

See https://www.gnu.org/software/emacs/manual/html_node/emacs/Identifier-Search.html

In older EMACS versions, e.g. 20.7, tags-case-fold-search was not existing, only case-fold-search, but it seemed to have the same effect.

Dired Mode to Search File Content

To enter dired-mode do

C-x d directory <RET>

M-x dired

"i" adds a listing of the sub-directory where the cursor is and jumps there
C-u C-SPC brings the cursor back
Menu Regexp, Mark... allows to mark files by a regexp e.g. \.vmc$ selects file extension "vmc"
Menu Operate, Search Files... (dired-do-search) allows to search for content.
M-, finds the next hit.
This will open a new buffer for each file with hits.
If you only need a list of files containing hits, then you might use a "Shell Command" operating on marked files:
! find "redetho" *

When the files are all in the same directory or in not too many sub-directories:

M-x dired
Mark each file using "m" or using "% m" \.ext$ , which is a regexp to search for the file extension "ext"
Starting "Query Replace" with "Q" (capital Q!) did not work for me. I got to use the menu Operate... > Query Replace in files
^ moves up one directory
a moves down into a directory without opening a new buffer (in contrast to "f" oder RET)
R moves marked files into a directory

My Dired Customisations

I customised dired-listing-switches to "-Al")

-A omits the . and .. directory entries. -l always has to be present.

On Windows, Dired is using a Lisp emulation of ls. My preferences:

ls-lisp-dirs-first t
ISO Date/Time:
- ls-lisp-format-time-list (quote ("%Y-%m-%d %H:%M:%S" "%Y-%m-%d %H:%M:%S")))
- ls-lisp-use-localized-time-format t

Search and Replace using Regular Expressions

The following examples are source code changes. They also work with M-x tags-query-replace

Example 1 - Re-Order Parts of Identifiers

To change

xyz_Q_OFFS or xyz_D_OFFS

Q_xyz_OFFS respectively D_xyz_OFFS

Query regexp:

$[A-Z0-9]+$_$[DQ]$_OFFS

Replace regexp:

\2_\1_OFFS

Example 2 - Replace Part of a String

From

aOutVol

MA_A_OutVol

$\s-$a$[A-Z][a-zA-Z0-9]+$

\1MA_A_\2

Example 3 - Change Upper/Lower Case

From e.g.

EB_VolAttOsc1_OFFS

EB_VOLATTOSC1_OFFS

i.e. to upper case

$EB_$$[A-Z][a-zA-Z0-9]+$$_OFFS$

\1\,(upcase \2)\3

Similarly: downcase

Example 4 - String with Embedded Blanks

abc[ ]efg

ASM-Mode with my AVR Changes

Comments

; one or twice or three-times according to hierarchy level.

M-j new line in a comment

M-; insert or re-align comment

Miscellaneous

Set How Line Endings are Written

M-x set-buffer-file-coding-system

then: unix or dos or mac

I should also try C-x RET f

Copy a Rectangle

C-x SPC then size the rectangle using the cursor keys, then C-c

Beautify

Open the file and then indent it by indenting the entire region:

M-x find-file /path/to/file RET

C-x h (M-x mark-whole-buffer)

C-M-\ (M-x indent-region)

Version Control

VC is enabled automatically whenever you visit a file governed by a version control system. To disable VC entirely, set the customisable variable vc-handled-backends to nil (see Customizing VC).

See https://www.gnu.org/software/emacs/manual/html_mono/emacs.html

Track Files That Change Outside EMACS.

Use

M-x auto-revert-mode

See http://www.gnu.org/software/emacs/manual/html_mono/efaq-w32.html

Spell Checking

Change language using M-x ispell-change-dictionary (M-x isp-c-d will also do), then e.g. "deutsch"

Re-Read a File with Correct File Encoding

If EMACS heuristics fails, which tries to guess a file's encoding, do:

C-x RET r or M-x revert-buffer-with-coding-system

See (info "(emacs) Specify Coding") for details.

Find Non-ASCII Characters in a Buffer

Use the search regexp

[[:nonascii:]]

The cursor will be set past the found character.

Load `init.el` Again

M-: (load user-init-file)

Re-Load EMACS Lisp Code

Open the Lisp code file in EMACS
M-x eval-buffer

Run EMACS Lisp File

Either put in the *scratch* buffer (require 'xyz) or do M-x lisp-interaction-mode

For More Tips and Tricks See Also

"Hack EMACS" Rick Dillon on Youtube

"Publishing a book using org-mode" from Lakshmi Narasimhan https://www.craftofcoding.com/publishing-book-using-org-mode/

Emacs org-mode examples and cookbook http://ehneilsen.net/notebook/orgExamples/org-examples.html