Protesilaos Stavrou

🏆 I provide private lessons on Emacs, Linux, and Life in general: https://protesilaos.com/coach/. Lessons continue throughout the year.

Change Log of logos (logos.el)

The newest release is at the top. For further details, please consult the manual: https://protesilaos.com/emacs/logos.

Version 1.1.0 on 2023-06-20

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.

Version 1.0.0 on 2022-10-19

  • Revised the fallback condition of the user option logos-outline-regexp-alist (it comes into effect when the logos-outlines-are-pages is non-nil).

    The previous value did not account for the buffer-local values of outline-regexp or page-delimiter, nor did it adapt to any changes in their respective values. Instead, it would capture whatever the value was at the time of the symbol's declaration.

    We remove the t condition altogether and instead handle the fallback value internally. Logos will return the current buffer-local value of outline-regexp or page-delimiter, in this order of priority.

    Put simply, this has the same intent as before, but works properly.

  • Introduced a check to guard against a void outline-regexp. The previous value would cause a problem if the outline-regexp had not been set yet. In a typical Emacs session, even on 'emacs -Q', the outline-regexp is set in the scratch buffer, so we have a valid value at the outset. However, when the user changes the initial-buffer-choice or opens Emacs directly for a given file, the outline-regexp can be void.

    Thanks to Xiaoduan for informing me about this error and for testing my code on how to fix it. This was done via a private channel and is shared with permission.

  • Implemented the user option logos-hide-cursor. It hides the cursor when logos-focus-mode is enabled. Note that this user option is always buffer-local. Use setq-default to set its default global value (same as with other user options that apply to logos-focus-mode (read the manual)).

    Thanks to Marcel Ventosa for suggesting the idea of hiding the cursor. This was done via a private channel and is shared with permission.

  • Clarified the documentation of logos-focus-mode-extra-functions. It is intended for use by those who are prepared to write custom functions in the spirit of those already used in logos.el to affect the buffer when logos-focus-mode is enabled.
  • Added the missing autoload cookie to logos-focus-mode. This means that it shows up in the completion candidates of M-x even if the logos library has not been called via require.

Version 0.5.0 on 2022-09-01

  • Introduced the function logos-update-fringe-in-buffers. This is a convenience function for those who (i) set the user option logos-hide-fringe to a non-nil value and (ii) switch themes while logos-focus-mode is enabled in one or more buffers. This convenience function updates the fringe face to be consistent with the current theme (we technically make the fringe invisible, instead of outright disabling it, as that would not be desirable). It needs to be assigned to a hook that gets called in the post-theme-load phase. The modus-themes or the ef-themes (both by me) provide such a hook. Otherwise the Logos manual explains how to implement one for any theme. Read: https://protesilaos.com/emacs/logos#h:6a254fa0-5706-4032-8a8b-233ffb1f0e6b.

  • Implemented the logos-focus-mode-map. This is a keymap that is active when logos-focus-mode is enabled in the buffer. One can, for example, use it to bind the arrow key to page motions, such as logos-forward-page-dwim.

    Remember that, by default, pages are delimited with the Control-L character (^L), though Logos can treat different delimiters as "page" separators (e.g. Org headings and a horizontal rule of five hyphens). Consult the user options logos-outlines-are-pages, logos-outline-regexp-alist, and check the manual for relevant simple and more advanced code samples. My current setup for those: 

      (setq logos-outlines-are-pages t)
  (setq logos-outline-regexp-alist
        `((emacs-lisp-mode . ,(format "\\(^;;;+ \\|%s\\)" logos--page-delimiter))
          (org-mode . ,(format "\\(^\\*+ +\\|^-\\{5\\}$\\|%s\\)" logos--page-delimiter))
          (markdown-mode . ,(format "\\(^\\#+ +\\|^[*-]\\{5\\}$\\|^\\* \\* \\*$\\|%s\\)" logos--page-delimiter))
          (conf-toml-mode . "^\\[")
          (t . ,(or outline-regexp logos--page-delimiter))))

  • Added the logos-repeat-map. This is a keymap that gets enabled when the built-in repeat-mode is active (Emacs 28 or higher). This means that page motions, C-x ] and C-x [, can be repeated by following them up with either ] or [. The repetition stops when another command is invoked.

    Thanks to Lucy McPhail for the patch: https://lists.sr.ht/~protesilaos/logos/patches/34101. The change is below the ~15 line threshold and thus requires no copyright assignment to the Free Software Foundation.

  • Wrote documentation on how to auto-toggle menu and tool bars while using the logos-focus-mode. This is complementary to user options provided by Logos and shows how flexible and extensible the code is. Thanks to Ypot for raising the question in issue 2 on the GitHub mirror: https://github.com/protesilaos/logos/issues/2.

    [ Never hesitate to ask for help if you want to do something with Logos but are not sure how. ]

  • Specified the :version of all user-facing variables. This is helpful while perusing documentation strings in Help buffers, as any change will be assigned to the given version of Logos.

  • Clarified the doc string of the logos-variable-pitch user option with regard to prog-mode buffers. It now reads thus:

    When non-nil, use variable-pitch-mode where appropriate. In programming modes the default font is always used, as that is assumed to be a monospaced typeface, which is appropriate for spacing-sensitive text.

    This is only relevant when logos-focus-mode is enabled.

  • Documented some user options for the built-in eww which make its contents behave like the rest of Emacs in terms of the use of fonts and the filling of paragraphs. In brief: 

      (setq shr-max-width fill-column)
  (setq shr-use-fonts nil)

    This is relevant for Logos as we then do not need to implement special casing for logos-focus-mode to work nicely with eww (I am personally annoyed when a buffer has its own opinions about font settings).

    Thanks to Ypot for discussing this in issue 4 on the GitHub mirror: https://github.com/protesilaos/logos/issues/4.

    [ For font-related customisations check the fontaine package on GNU ELPA (by me). ]

  • Named the mailing list address as the Maintainer: of Logos. Together with the other package headers, they help the user find our primary sources and/or communication channels. This change conforms with work being done upstream in package.el by Philip Kaludercic. I was informed about it here: https://lists.sr.ht/~protesilaos/general-issues/%3C875ykl84yi.fsf%40posteo.net%3E.

Version 0.4.0 on 2022-06-02

  • The Git repo is now hosted on SourceHut. Mirrors are available on GitHub and GitLab—users can open issues there if they find it difficult to use the official mailing list. The sources:
  • The new user option logos-hide-fringe conceals the fringe by applying the same background as the default face. It does not interfere with fringe-mode, such as by adjusting its size. This option complements logos-olivetti and is only relevant if the fringe face has a distinct background.
  • The new logos-focus-mode-extra-functions is an ordinary hook that unlocks the potential of logos-focus-mode by allowing the user to trigger any effect when the mode is toggled. Its doc string references functions from logos.el that can be adapted at the user level to pursue varied ends, while the manual furnishes a ready-to-use sample for org-indent-mode. This feature was inspired by the inquiry of Ypot in issue 1 over at the GitHub mirror: https://github.com/protesilaos/logos/issues/1.
  • The default value of the user option logos-outline-regexp-alist now includes an entry for markdown-mode to determine what constitutes a heading there. This helps with motions such as logos-forward-page-dwim while it makes Markdown equally useful for a focused reading or presentation (with logos-focus-mode).
  • The manual includes a link to a publication of mine where I explain what the "devel" version of GNU ELPA is and how to make use of it: https://protesilaos.com/codelog/2022-05-13-emacs-elpa-devel/.

Version 0.3.0 on 2022-03-30

This release basically contains one major refinement about how buffer narrowing is handled. In detail:

  1. If logos-outlines-are-pages is non-nil, it now includes the match of the page-delimiter regexp in the narrowed region and leaves point right after the page-delimiter—so in Org mode, after the stars. (It is better to leave point there than at the very beginning of the narrowed buffer to match the behavior of logos-forward-page-dwim when the buffer is not narrowed.) The inclusion of the delimiter helps retain any folding functionality associated with that line (e.g. Org headings).
  2. To avoid skipping pages in the narrowed case when point is at their outer boundaries, logos checks if you are right at the start of a page-delimiter and if so moves past the delimiter in the opposite direction of the given motion: so if you are moving back, it puts you after the delimiter, and if you are moving forward it puts you before the delimiter. (The bug was that if the point was at point-max while narrowed and moving forward, it would skip past a page and the same in the opposite direction with point-min.)
  3. Changed logos-narrow-dwim to call logos--narrow-to-page instead of narrow-to-page, so that it too includes the page-delimiter match in the page.
  4. The logos--page-p now always checks for the right delimiter, which may be that of the outline if logos-outlines-are-pages is non-nil. Whereas before it was hard-coded to the generic page-delimiter.

Thanks to Omar Antolín Camarena for commit 8c2e85033db982ef13a5e041012dc45d86d9de32 which covers the first three of the aforementioned points. The contribution was sent as a patch via email. Omar has already assigned copyright to the Free Software Foundation.

Version 0.2.0 on 2022-03-17

All functions or variables referenced herein have documentation strings and are also documented in the manual.

  • Implemented the user option logos-olivetti which is a buffer-local variable that is read when logos-focus-mode is enabled. This provides the glue code to integrate Logos with olivetti. Olivetti is a package by Paul W. Rankin which centres the contents of the buffer in its window.
  • Removed the do-it-yourself snippet that was present in the manual for piecing together Logos and Olivetti. The documentation has been updated accordingly. Users who followed the old method are advised to review their configurations.
  • Abstracted the state handling of the variables and modes that are affected by logos-focus-mode, based on feedback by Daniel Mendler. This improves how the code is written and makes it easier to extend it.
  • Introduced the user options logos-indicate-buffer-boundaries and logos-buffer-read-only. Both are buffer-local and both take effect when logos-focus-mode is enabled. The former controls the indicate-buffer-boundaries while the latter determines whether the buffer should be put in a read-only mode.
  • Changed how user options are declared as buffer-local, by using the appropriate keyword of defcustom. Thanks to Philip Kaludercic for the patch, which was sent via email.
  • Wrote a node entry on how to write a regular expression that targets only specific Org heading levels. This pertains to user options logos-outlines-are-pages and logos-outline-regexp-alist.
  • Added keywords to the package metadata to help its discoverability.
  • Fixed typo in a function's doc string. Thanks to Remco van 't Veer for the contribution in merge request 1: https://gitlab.com/protesilaos/logos/-/merge_requests/1.
  • Fixed typo in the manual. Thanks to user Ypot for the contribution in merge request 2: https://gitlab.com/protesilaos/logos/-/merge_requests/2.
  • Appended an "Acknowledgements" section in the manual, which references the names of everyone involved in the development of this package.

Version 0.1.0 on 2022-03-11

In the beginning, there was prot-logos.el. A file that pieced together some code and configurations I had for presentations (part of my dotfiles). On 2022-03-02 I decided to take the code out of my personal setup and turn it into a general purpose package.

It occured to me that "logos" is a nice word though it might be a bit dull for an Emacs package, so I coined the backcronyms "L Only Generates Ostensible Slides" and "Logos Optionally Garners Outline Sections", which hopefully describe what this is all about.

Read the manual for the technicalities.