88beb0aa7ba2d968ab1f21353b38fdd1b226c527 — Protesilaos Stavrou 5 months ago 3ccd6b6 1.1.0
Update to version 1.1.0
3 files changed, 84 insertions(+), 7 deletions(-)

M logos.el
M CHANGELOG.org => CHANGELOG.org +80 -0
@@ 6,6 6,86 @@
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
:CUSTOM_ID: h:cf39d0d8-9299-4d1a-a625-c918429f9989

** The ~logos-focus-mode-extra-functions~ has a new name
:CUSTOM_ID: h:4599c0ac-a01d-4045-be2d-b1c45c92ae39

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:

#+begin_src emacs-lisp
(info "(elisp) Hooks")

** The ~logos-page-delimiter~ variable/function is now public
:CUSTOM_ID: h:d1677f40-7392-4433-9a52-a87edd97eb4f

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
:CUSTOM_ID: h:f06aaf6b-613f-4c48-814f-9143cc2e493e

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
:CUSTOM_ID: h:4f49cd65-f04a-4703-bbe6-399e8c5c8326

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
:CUSTOM_ID: h:b71866b6-393a-4bff-bb89-e52f5e2fca9d

M README.org => README.org +3 -6
@@ 4,9 4,9 @@
#+language:              en
#+options:               ':t toc:nil author:t email:t num:t
#+startup:               content
#+macro:                 stable-version 1.0.0
#+macro:                 release-date 2022-10-19
#+macro:                 development-version 1.1.0-dev
#+macro:                 stable-version 1.1.0
#+macro:                 release-date 2023-06-20
#+macro:                 development-version 1.2.0-dev
#+export_file_name:      logos.texi
#+texinfo_filename:      logos.info
#+texinfo_dir_category:  Emacs misc features

@@ 478,9 478,6 @@ end result can look like this:
#+cindex: User-level extensions to logos-focus-mode

[ ~logos-focus-mode-hook~ replaces ~logos-focus-mode-extra-functions~
  as part of {{{development-version}}}. ]

#+vindex: logos-focus-mode-hook
The ~logos-focus-mode-hook~ is a normal hook that runs when
~logos-focus-mode~ is enabled.  Each function is called without an

M logos.el => logos.el +1 -1
@@ 6,7 6,7 @@
;; Maintainer: Logos Development <~protesilaos/logos@lists.sr.ht>
;; URL: https://git.sr.ht/~protesilaos/logos
;; Mailing-List: https://lists.sr.ht/~protesilaos/logos
;; Version: 1.0.1
;; Version: 1.1.0
;; Package-Requires: ((emacs "27.1"))
;; Keywords: convenience, focus, writing, presentation, narrowing