To read my newspapers I load my RSS feed via the elfeed package.
…
Also, I identify any RSS feed entry that does not provide the full text. And those live in provisional status. My reflexes are to ask “there’s lots of full-text feeds, why bother with this truncation?”

Jeremy Friesen, A Walk Through My Digital Neighborhood

Jeremy is totally right! – it came to my mind immediately.

I’m using the Hugo static site generator to build this blog. Hugo uses content summaries to display a list of blog entries on the main page. As a result, the Elfeed entry shows a summary of the post instead of the full text.

Many of us – including me – are using Elfeed as an RSS reader, and I have realized that the truncated Elfeed entry may cause inconvenience to the Elfeed users.

Applying some tricks I was able to disable the automatic displaying of summaries on the main page. I hope it has become more comfortable for those who use Elfeed for reading RSS feeds.

Happy elfeeding!

– The Emacs Cat.

P.S. Thanks to Jeremy Friesen for the heads up.

Software reproducibility testing is a critical aspect of software development and maintenance. It ensures that software is reliable, consistent, and predictable and that it can be easily replicated and verified by others.

Ana Pustan, Reproducibility Testing: A Complete Guide

For many of us, it won’t be a surprise that the Emacs Org mode is perfectly suited for reproducibility testing.

In some of my projects I’m using gRPC, a modern open source high performance Remote Procedure Call (RPC) framework that can run in any environment. The gRPC framework is evolving very rapidly so I have to update it to the most recent stable version time to time. No doubt, I want to make sure that everything is working properly after the update.

I’ve built a tiny hello-world gRPC server for testing the update. I use grpcurl, a command-line tool that interacts with gRPC servers, as a client.

Now Emacs has to go be onstage.

The Server

I don’t like having to leave Emacs for too long so I run my server in Eshell.

The Client

The Org mode code blocks – that’s all we need now.

Listing of available services at localhost port 50051

#+begin_src bash :results verbatim
  grpcurl -plaintext localhost:50051 list
#+end_src

#+RESULTS:
: grpc.reflection.v1.ServerReflection
: grpc.reflection.v1alpha.ServerReflection
: helloworld.Greeter

Pressing C-c C-c when the point (cursor) is inside the code block shows 3 services available at localhost:50051 – 2 builtin services and our helloworld.Greeter service, the last one.

Inspecting helloworld.Greeter service

#+begin_src shell :results verbatim
  grpcurl -plaintext localhost:50051 describe helloworld.Greeter
#+end_src

#+RESULTS:
: helloworld.Greeter is a service:
: service Greeter {
:   rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
: }

OK, everything seems to be in order.

Inspecting helloworld.Greeter.SayHello method

#+begin_src bash :results verbatim
  grpcurl -plaintext localhost:50051 describe helloworld.Greeter.SayHello
#+end_src

#+RESULTS:
: helloworld.Greeter.SayHello is a method:
: rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );

Querying the server

Finally, let’s query the server.

#+begin_src bash :results verbatim
  grpcurl -plaintext -d '{"name": "world"}' localhost:50051 helloworld.Greeter.SayHello
#+end_src

#+RESULTS:
: {
:   "message": "Hello world!"
: }

That is the expected outcome – the server replied accordingly.

Now I can perform gRPC reproducibility testing every time after the update.

Happy emacsing!

– The Emacs Cat.

C++ is my primary programming language since – I can’t believe it myself – 1991 (yes, it was Turbo C++). As I’m going to do almost everything within Emacs 29.4 now – no doubt I want to have the C++ IDE in Emacs, in the same way I’m using Emacs as the Python IDE.

Thankfully, eglot, the Emacs client for the Language Server Protocol (LSP), is now – since version 29 – the part of Emacs. It remains to choose the appropriate LSP.

Choosing a Language Server

I’ve settled on clangd, a powerful LSP for C++ based on the Clang C++ compiler. It provides an impressive set of features including error checking, code completion, cross-references, navigation, and others.

clangd is the part of the LLVM project and it can be downloaded from LLVM Download Page. Which version to download? It depends on OS/version you are using. I’m using Pop!_OS 22.04 (Ubuntu 22.04 fork); after researching, I came upon clang+llvm-17.0.6-x86_64-linux-gnu-ubuntu-22.04.tar.xz from this repository that contains pre-build binaries for my OS. It supports C++17 standard – that’s good enough for me.

I’ve unpacked the archive to ~/bin/LLVM-17.0.6/ then added $HOME/bin/LLVM-17.0.6/bin to the $PATH envvar.

$ clangd --version
clangd version 17.0.6 (https://github.com/llvm/llvm-project 6009708b4367171ccdbf4b5905cb6a803753fe18)
Features: linux
Platform: x86_64-unknown-linux-gnu

Configuring clangd

Clangd stores its configuration in YAML files. I’m using per-project configuration file .clangd – clangd searches for it in all parent directories of the active file.

Below is my simple and straightforward .clangd for some of my projects.

# Enable all warnings, use C++17 standard, specify include directories.
CompileFlags:
  Add: [-xc++, -Wall, -std=c++17, -I/home/magnolia/workspace/devel, -I/home/magnolia/lib/grpc/include, -I/home/magnolia/lib/spdlog/include]
  Remove: [-W*]      # Strip all other warning-related flags
  Compiler: clang++  # Use `clang++` explicitly

It is placed in the top level directory of my project. You can find more about clangd configuration here.

Now we can return back to the Emacs configuration.

Emacs Configuration for C++

Using Eglot

(require 'eglot)
(add-hook 'c-mode-hook 'eglot-ensure)
(add-hook 'c++-mode-hook 'eglot-ensure)
(add-hook 'c-or-c++-mode-hook 'eglot-ensure)

The Eglot session will start automatically every time you open the C/C++ file in a buffer. If the Eglot session for the current C/C++ buffer has started successfully it displays the following message in the Emacs minibuffer:

[eglot] Connected! Server `clangd' now managing `(c++-mode c-mode)' buffers in project ...

Visual Improvements

Highlighting symbols and numbers in the source code.

;; Highlights the word/symbol at point and any other occurrences in
;; view. Also allows to jump to the next or previous occurrence.
;; https://github.com/nschum/highlight-symbol.el
(use-package highlight-symbol
  :ensure t
  :config
  (setq highlight-symbol-on-navigation-p t)
  (add-hook 'prog-mode-hook 'highlight-symbol-mode))

;; Emacs minor mode that highlights numeric literals in source code.
;; https://github.com/Fanael/highlight-numbers
(use-package highlight-numbers
  :ensure t
  :config
  (add-hook 'prog-mode-hook 'highlight-numbers-mode))

C++ Headers

Please, treat C headers as C++ ones.

;; .h files to open in c++-mode rather than c-mode.
(add-to-list 'auto-mode-alist '("\\.h$" . c++-mode))

Code Styles

(setq c-default-style "stroustrup")
(setq c-basic-indent 4)
(setq c-basic-offset 4)

I’m using the Stroustrup C++ code style that is very similar to the K&R (Kernighan & Ritchie) code style.

The c-style-alist Elisp variable contains a list of all predefined code styles. Pick a style that suits you.

Indentation Inside of Namespaces

;; emacs-fu: don’t indent inside of C++ namespaces
;; http://brrian.tumblr.com/post/9018043954/emacs-fu-dont-indent-inside-of-c-namespaces
(c-set-offset 'innamespace 0)

I prefer to have the code unindented inside of a namespace as shown below,

namespace tec {

class Client {
public:
    Client() {
        // ...
    }

    int get_id() {
        // ...
    }
}; // ::Client

} // ::tec

rather than

namespace tec {

    class Client {
    public:
        Client() {
            // ...
        }

        int get_id() {
            // ...
        }
    }; // ::Client

} // ::tec

Spaces vs Tabs

Yes, I’m using spaces instead of tabs for indentation.

;; Spaces instead of tabs when indenting.
(setq-default indent-tabs-mode nil)

Trailing Tabs and Spaces

A builtin package that shows/deletes useless trailing tabs and spaces. You can also use M-x delete-trailing-whitespace to remove all trailing white-spaces in a buffer interactively.

;; http://www.reddit.com/r/emacs/comments/2keh6u/show_tabs_and_trailing_whitespaces_only/
(use-package whitespace
  :config
  ;; Commented since there are too many 'valid' whitespaces in some modes.
  ;; (setq-default show-trailing-whitespace t)
  (setq whitespace-style '(face tabs trailing))
  (set-face-attribute 'whitespace-tab nil
      :background "red"
      :foreground "yellow"
      :weight 'bold)
  (add-hook 'prog-mode-hook 'whitespace-mode)
  ;; Delete trailing tabs and spaces on save of a file.
  (add-hook 'before-save-hook 'whitespace-cleanup)
)

Clangd with Flymake

Flymake is a minor Emacs mode performing on-the-fly syntax checks. I’m using the flymake built-in Emacs package as an Eglot front-end for syntax checks.

(require 'flymake)

My custom my/flymake-toggle-diagnostics-buffer function toggles the Flymake diagnostics buffer window.

If there is the Flymake diagnostics buffer associated with a file in the current buffer, it shows the diagnostics buffer in the new window and switches to it. If the current buffer is the Flymake diagnostics buffer, it closes it. Otherwise it just shows the error message.

(defun my/flymake-toggle-diagnostics-buffer ()
  (interactive)
  ;; Check if we are in the diagnostics buffer.
  (if (string-search "*Flymake diagnostics" (buffer-name))
      (delete-window)
    (progn
      ;; Activate the Flymake diagnostics buffer.
      ;; and switch to it
      (flymake-show-buffer-diagnostics)
      (let ((name (flymake--diagnostics-buffer-name)))
        (if (get-buffer name)
            (switch-to-buffer-other-window name)
          (error "No Flymake diagnostics buffer found")
          )))))

I’ve bound this function to the F7 key globally since I’m using F7 in other programming modes as well.

(global-set-key [(f7)] #'my/flymake-toggle-diagnostics-buffer)

;; Additional bindings.
(global-set-key (kbd "C-c f b") #'flymake-show-buffer-diagnostics)
(global-set-key (kbd "C-c f p") #'flymake-show-project-diagnostics)

The screenshot below shows what happens if you press F7 while editing a C++ file managed by Eglot + Flymake.

Treemacs

From looking at the screenshot above, you can see using of Treemacs, a tree layout file explorer for Emacs.

I can highly recommend to use it for any project you’re working on in conjunction with the excellent Projectile and Ivy packages.

(use-package ivy
  :config
  (ivy-mode)
  (setq ivy-use-virtual-buffers t)
  (add-hook 'after-init-hook (lambda () (setq ivy-height (/ (window-height) 2))))
)

(use-package projectile
  :ensure t
  :config
  (projectile-global-mode)
  (setq projectile-enable-caching t)
  (setq projectile-completion-system 'ivy)
)

(use-package treemacs :ensure t)
(use-package treemacs-projectile :ensure t)

I’ve bound Treemacs to F12 globally.

(global-set-key [(f12)] #'treemacs-select-window)

Press ? when in the Treemacs window to see all commands available. Press q to close the Treemacs window.

Code Completion

I’m using the company package, a modular in-buffer completion framework for Emacs, as an Eglot front-end for code completion; it integrates with Eglot seamlessly.

;;;; `COMPANY'
(use-package company
  :ensure t
  :config
  (setq company-idle-delay 0)
  (setq company-minimum-prefix-length 2)
  (setq company-show-numbers t)
  ;; To prevent default down-casing.
  ;; https://emacs.stackexchange.com/questions/10837/how-to-make-company-mode-be-case-sensitive-on-plain-text
  (setq company-dabbrev-downcase nil)
  ;; 2023-01-13 From a Reddit post on mixed case issue.
  (setq company-dabbrev-ignore-case nil)
  (setq company-dabbrev-code-ignore-case nil))

;; Use `company' everywhere.
(add-hook 'after-init-hook 'global-company-mode)

Code Navigation

My favorite tool for code navigation in the current buffer is the excellent imenu-list package. Powered by Eglot, it shows almost everything you want to see.

Now your Emacs looks like a full-featured C++ IDE – and it is, actually.

;; Show the current buffer's imenu entries in a separate buffer
(use-package imenu-list
  :ensure t
  :config
  (setq imenu-list-focus-after-activation t)
  (global-set-key (kbd "C-.") #'imenu-list-minor-mode)
)

I’ve bound imenu-list-minor-mode to C-.; this key chord will toggle the Imenu buffer on/off.

Alternatively, you can use Treemacs to navigate through the code and files on a per-project basis.

“Classic” default navigation keys will also work with all files in your project.

xref-find-definitions

M-. to find the definition of the identifier at point.

xref-go-back

M-, to return back to where you invoked the xref-find-definitions command.

xref-find-references

M-? to find references to the identifier at point.

These functions are now powered by Eglot.

Appendix A

All the Icons

As you can see from the screenshots above, I like to see icons wherever possible – in treemacs, dired, ibuffer, company and other modes. To achieve that, all you need is to install the corresponding packages.

;; https://github.com/domtronn/all-the-icons.el
(use-package all-the-icons :ensure t)

(use-package all-the-icons-dired :ensure t)
(add-hook 'dired-mode-hook 'all-the-icons-dired-mode)

(use-package all-the-icons-ibuffer :ensure t
  :init (all-the-icons-ibuffer-mode 1)
  :hook (ibuffer-mode . all-the-icons-ibuffer-mode))

(use-package treemacs-all-the-icons :ensure t)

(use-package all-the-icons-ivy :ensure t
  :after all-the-icons
  :config (all-the-icons-ivy-setup))

Appendix B

A Note for Tree-Sitter Users

Happy emacsing!

– The Emacs Cat.

P.S. Emacs 30.1 has been released on February 23. Thanks for everyone involved with this great project!

P.P.S. Mickey Petersen has published his excellent review on what’s new in this release.

Python is one of my programming languages I’m using for both work and home life – no doubt, I’d want to use Emacs as an IDE for Python programming. There is a certain set of features we’d expect to have in any IDE: 1) code completion, 2) code navigation, 3) error checking.

Thanks to the fact that both eglot, the Emacs client for the Language Server Protocol (LSP), and tree-sitter, a powerful parsing library, are now – since version 29 – the parts of Emacs, It should not be too hard to construct a lightweight and fast Python IDE.

Choosing a Language Server

There are a number of the language servers for Python available these days – pylsp, pyls, pyright, jedi-language-server. After a series of tests, I’ve settled on pyright, an open syntax and type checker from Microsoft (sic!) used in Visual Studio Code, the fast and reliable one, as for me.

The Pyright documentation – a bit weird – claims that Pyright is just static type checker for Python. However, as we’ll see later, Pyright can do much more than just type checks.

A note on the Tree-Sitter package

The tree-sitter package is optional – I’m using it for pretty-looking source code fontification mainly. However, if you want to use it you have to pay attention to the following quote from the Mickey Petersen’s ‘Mastering Emacs’ book:

And in Emacs 29, support for tree-sitter is built in. Sort of. It’s an optional extra, so you must compile Emacs from source, or hope that someone else will do it for you.

Neither tree-sitter nor Emacs come installed with language grammars. Just like kids’ toys and batteries, they’re sold separately. So you’re required to download and compile the sources for each language grammar you want to use.

– Mastering Emacs by Mickey Petersen.

If you are – like me – on Linux, the best way to setup language grammars is to compile them from the source code; you can find all grammars available on the tree-sitter repository. More details at How to Get Started with Tree-Sitter.

Python prerequisites

First of all, we need to install the following Python packages – pyright (the language server) and jsonrpc (the transport layer for the LSP).

[p3] $ pip install pyright
[p3] $ pip install jsonrpc

I’m running Python in the virtual environment, “p3” in my case.

Error checking with Pyright

Eglot automatically finds a suitable LSP – Pyright in our case – when you are opening a Python file. I’m using the default Pyright settings, no extra tuning required.

Pyright LSP with Flymake

Flymake is a minor Emacs mode performing on-the-fly syntax checks. I’m using the flymake built-in Emacs package as an Eglot front-end for syntax checks.

(require 'flymake)

My custom my/flymake-toggle-diagnostics-buffer function toggles the Flymake diagnostics buffer window.

If there is the Flymake diagnostics buffer associated with a file in the current buffer, it shows the diagnostics buffer in the new window and switches to it. If the current buffer is the Flymake diagnostics buffer, it closes it. Otherwise it just shows the error message.

(defun my/flymake-toggle-diagnostics-buffer ()
  (interactive)
  ;; Check if we are in the diagnostics buffer.
  (if (string-search "*Flymake diagnostics" (buffer-name))
      (delete-window)
    (progn
      ;; Activate the Flymake diagnostics buffer.
      ;; and switch to it
      (flymake-show-buffer-diagnostics)
      (let ((name (flymake--diagnostics-buffer-name)))
        (if (get-buffer name)
            (switch-to-buffer-other-window name)
          (error "No Flymake diagnostics buffer found")
          )))))

I’ve bound this function to the F7 key globally since I’m using F7 in other programming modes as well.

(global-set-key [(f7)] #'my/flymake-toggle-diagnostics-buffer)

;; Additional bindings.
(global-set-key (kbd "C-c f b") #'flymake-show-buffer-diagnostics)
(global-set-key (kbd "C-c f p") #'flymake-show-project-diagnostics)

The screenshot below shows what happens if you press F7 while editing a Python file managed by Eglot + Flymake.

As you can see, Pyright can do much more than just type checks.

Code completion

I’m using the company package, a modular in-buffer completion framework for Emacs, as an Eglot front-end for code completion; it integrates with Eglot seamlessly.

;;;; `COMPANY'
(use-package company
  :ensure t
  :config
  (setq company-idle-delay 0)
  (setq company-minimum-prefix-length 2)
  (setq company-show-numbers t)
  ;; To prevent default down-casing.
  ;; https://emacs.stackexchange.com/questions/10837/how-to-make-company-mode-be-case-sensitive-on-plain-text
  (setq company-dabbrev-downcase nil)
  ;; 2023-01-13 From a Reddit post on mixed case issue.
  (setq company-dabbrev-ignore-case nil)
  (setq company-dabbrev-code-ignore-case nil))

;; Use `company' everywhere.
(add-hook 'after-init-hook 'global-company-mode)

Code navigation

I’m using the default key bindings for

xref-find-definitions

M-. to find the definition of the identifier at point.

xref-go-back

M-, to return back to where you invoked the xref-find-definitions command.

xref-find-references

M-? to find references to the identifier at point.

These functions are now powered by Eglot.

Final notes

I can recommend to force using Eglot for Python explicitly –

(require 'eglot)
(add-hook 'python-mode-hook 'eglot-ensure)

A note for Tree-Sitter users

If you are using Tree-Sitter for Python, it’s recommended to remap the python-mode to the Tree-Sitter specific python-ts-mode.

(add-to-list 'major-mode-remap-alist '(python-mode . python-ts-mode))

If this is the case, do not forget to force using Eglot for this mode as well.

(add-hook 'python-ts-mode-hook 'eglot-ensure)

Happy emacsing!

Some time ago, I decided to customize my Emacs startup screen in order to display something helpful for me. Ultimately, after much consideration, I settled on the following items I just want to see on my startup screen: 1) 3-month calendar, 2) agenda, 3) diary, 4) something just for fun.

No doubt, there are a number of packages that can assist you in making a pretty good-looking startup screen – like enlight, for instance. However, I decided to construct my own startup screen, a very simple one.

It requires having two command line utilities installed on your system: fortune to print out a random epigram, and calendar to print out some of the events that have occurred on the current date in the past. If you, like me, are using Linux or macOS – it will not be difficult to install them.

And this is what I got…

In the .emacs init file

First of all, disable the builtin startup screen.

(setq inhibit-startup-screen t)

Then add a startup hook.

(add-hook 'emacs-startup-hook
  (lambda ()
    (let* ((buffer-today (get-buffer-create "*today*"))
           (buffer-calendar "*Calendar*")
           (buffer-agenda "*Org Agenda*")
           (buffer-diary "*Fancy Diary Entries*"))
      ;; Call calendar first to obtain the current date
      ;; required to display the diary.
      (calendar)
      (diary)
      (org-agenda-list)
      ;; Fill and show the Today Events buffer.
      ;; NOTE: requires `fortune' and `calendar' command line utilities.
      (switch-to-buffer buffer-today)
      (call-process "fortune" nil buffer-today)
      (insert "\n")
      (call-process "calendar" nil buffer-today)
      (goto-char 0)
      (toggle-truncate-lines)
      ;; Maximize the Today Events window
      (delete-other-windows)
      ;; Show Agenda in the lower left quadrant.
      (split-window-vertically)
      (other-window 1)
      (switch-to-buffer (get-buffer buffer-agenda))
      (split-window-horizontally)
      ;; Try to show Diary in the lower right quadrant.
      (other-window 1)
      (if (get-buffer buffer-diary)
          ;; If Diary exists then show it ...
          (switch-to-buffer (get-buffer buffer-diary))
        ;; ... else show the scratch buffer.
        (let* ((buffer-scratch (switch-to-buffer (get-buffer "*scratch*"))))
          (goto-char (point-max))
          (insert (format-time-string "\n;; No diary entries for %A %d %b")))
        )
      ;; Go back to the Today Events buffer.
      (other-window -2)
      (split-window-horizontally)
      ;; Show Calendar in the upper left quadrant.
      (switch-to-buffer (get-buffer buffer-calendar))
      )))

The startup screen

Happy emacsing!