From 88beb0aa7ba2d968ab1f21353b38fdd1b226c527 Mon Sep 17 00:00:00 2001 From: Protesilaos Stavrou Date: Tue, 20 Jun 2023 15:27:28 +0300 Subject: [PATCH] Update to version 1.1.0 --- CHANGELOG.org | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.org | 9 ++---- logos.el | 2 +- 3 files changed, 84 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.org b/CHANGELOG.org index e8d8af4..5138af8 100644 --- a/CHANGELOG.org +++ b/CHANGELOG.org @@ -6,6 +6,86 @@ The newest release is at the top. For further details, please consult the manual: . +* Version 1.1.0 on 2023-06-20 +:PROPERTIES: +:CUSTOM_ID: h:cf39d0d8-9299-4d1a-a625-c918429f9989 +:END: + +** The ~logos-focus-mode-extra-functions~ has a new name +:PROPERTIES: +:CUSTOM_ID: h:4599c0ac-a01d-4045-be2d-b1c45c92ae39 +:END: + +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: + +#+begin_quote +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’. +#+end_quote + +To read the manual, evaluate this inside of Emacs: + +#+begin_src emacs-lisp +(info "(elisp) Hooks") +#+end_src + +** The ~logos-page-delimiter~ variable/function is now public +:PROPERTIES: +:CUSTOM_ID: h:d1677f40-7392-4433-9a52-a87edd97eb4f +:END: + +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 +:PROPERTIES: +:CUSTOM_ID: h:f06aaf6b-613f-4c48-814f-9143cc2e493e +:END: + +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 +:PROPERTIES: +:CUSTOM_ID: h:4f49cd65-f04a-4703-bbe6-399e8c5c8326 +:END: + +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: . + * Version 1.0.0 on 2022-10-19 :PROPERTIES: :CUSTOM_ID: h:b71866b6-393a-4bff-bb89-e52f5e2fca9d diff --git a/README.org b/README.org index 6a91934..9c920ae 100644 --- a/README.org +++ b/README.org @@ -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: :END: #+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 diff --git a/logos.el b/logos.el index e6b3303..b27a5c0 100644 --- a/logos.el +++ b/logos.el @@ -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 -- 2.45.2