Emacs: logos version 1.1.0

2023-06-20

This package provides a simple approach to setting up a “focus mode” for Emacs. It uses the page-delimiter (typically the ^L character) or the outline-regexp together with some commands to move between pages whether narrowing is in effect or not. It also provides some optional stylistic tweaks which come into effect when the buffer-local logos-focus-mode is enabled. The manual shows how to extend the code to achieve the desired result.

• Package name (GNU ELPA): logos
• Official manual: https://protesilaos.com/emacs/logos
• Change log: https://protesilaos.com/emacs/logos-changelog
• Git repo on SourceHut: https://git.sr.ht/~protesilaos/logos
  • Mirrors:
    • GitHub: https://github.com/protesilaos/logos
    • GitLab: https://gitlab.com/protesilaos/logos
• Mailing list: https://lists.sr.ht/~protesilaos/logos
• Video demo: https://protesilaos.com/codelog/2022-03-11-emacs-logos-demo/
• Backronyms: ^L Only Generates Ostensible Slides; Logos Optionally Goes through Outline Sections

Below are the release notes.

---

The logos-focus-mode-extra-functions has a new name

It is now called logos-focus-mode-hook to conform with the conventions surrounding Emacs Lisp packaging. The old name is deprecated and will be removed in the future. The relevant warnings are in place to inform users of the change.

The logos-focus-mode-extra-functions had the unfortunate connotation of being an irregular hook, i.e. one that runs with arguments. Whereas this one is a regular hook that passes no arguments to the functions it calls. Quoting from the Emacs Lisp Reference Manual:

If the hook variable’s name does not end with ‘-hook’, that indicates it is probably an “abnormal hook”. These differ from normal hooks in two ways: they can be called with one or more arguments, and their return values can be used in some way. The hook’s documentation says how the functions are called and how their return values are used. Any functions added to an abnormal hook must follow the hook’s calling convention. By convention, abnormal hook names end in ‘-functions’.

To read the manual, evaluate this inside of Emacs:

(info "(elisp) Hooks")

The logos-page-delimiter variable/function is now public

Renaming the logos-page-delimiter function and variable is necessary as both can safely be included in user-defined code.

In the context of Elisp packaging, a “private” symbol is denoted by a double dash in its name. Such code is intended for internal use: it may be redefined or altogether removed without further notice. Whereas a “public” symbol comes with the implicit guarantee that the developer will take good care to preserve its behaviour and/or document any breaking changes.

Functions that set state have a more descriptive name

This concerns logos--mode, hereby renamed to logos-set-mode-arg, and logos--set, which is now called logos-set-buffer-local-value.

The intent is to make the code public as well as to better describe what it does already at the naming level.

As always, the relevant arrangements are in place to notify users of the change.

The Git repository also includes a README.md

The project has a README.org file which contains the project’s documentation and is exported to the Info page format. A new README.md is supplied as well to provide the basics of what logos is, link to its video demo, and further resources.

Thanks to Dave Abrahams for asking me to put a video demo in the README. This inspired me to update this repository to be in the style of the others I also maintain. Dave’s comment was made in issue 12 on the GitHub mirror: https://github.com/protesilaos/logos/issues/12.