#+TITLE: Change log of logos
#+AUTHOR: Protesilaos Stavrou
#+EMAIL: info@protesilaos.com
#+OPTIONS: ':nil toc:nil num:nil author:nil email:nil
#+STARTUP: content

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

#+toc: headlines 1 insert TOC here, with one headline level

* Version 1.2.0 on 2024-09-03
:PROPERTIES:
:CUSTOM_ID: h:c1cd618c-0de7-4a13-9df7-ef28b99e3857
:END:

This version introduces minor refinements to an already stable
package.

** The ~logos-update-fringe-in-buffers~ works with ~enable-theme-functions~
:PROPERTIES:
:CUSTOM_ID: h:d3e52d5c-0765-4780-a47f-145f8af30a4b
:END:

It is possible to hide the fringes when ~logos-focus-mode~ is enabled
by setting the user option ~logos-hide-fringe~ to a non-nil value. To
make sure that the proper colours are applied when the theme changes,
users must also set up the ~logos-update-fringe-in-buffers~ to run
after the theme is loaded.

In versions of Emacs before 29 there was no standard way to do this
(my themes (Modus, Ef, Standard) have always had the relevant "post
load" hook). With Emacs 29, users can now use the ~enable-theme-functions~
to make this work with all themes:

#+begin_src emacs-lisp
(add-hook 'enable-theme-functions #'logos-update-fringe-in-buffers)
#+end_src

** New ~logos-hide-header-line~ user option for ~logos-focus-mode~
:PROPERTIES:
:CUSTOM_ID: h:a1c473e9-c3ad-40f7-951f-5ddc7467cf14
:END:

Users can now optionally hide the header-line when ~logos-focus-mode~
is enabled in the current buffer. This is done by setting ~logos-hide-header-line~
to a non-nil value and then enabling the mode.

[ Remember to read the manual for all such options. ]

** Documented how to conditionally toggle ~org-indent-mode~
:PROPERTIES:
:CUSTOM_ID: h:9e0b4855-a634-44cc-af45-99a7893ae693
:END:

The ~logos-focus-mode~ operates in the current buffer to make the
changes that are needed for a more "focused" editing experience. Here
we extend it to work with Org's virtual indentation.

It disables ~org-indent-mode~ when ~logos-focus-mode~ is enabled and
restores it when ~logos-focus-mode~ is disabled.  The
~logos-set-mode-arg~ function takes care of the technicalities.

#+begin_src emacs-lisp
(defun my-logos-org-indent ()
  (when logos-focus-mode
    (logos-set-mode-arg 'org-indent-mode -1)))

(add-hook 'logos-focus-mode-hook #'my-logos-org-indent)
#+end_src

** Documented how to toggle the menu-bar, tool-bar, tab-bar, and tab-line
:PROPERTIES:
:CUSTOM_ID: h:72b44395-5647-4d2a-92a7-07598c30df37
:END:

Continuing from above, the following code block below shows how to
disable the ~menu-bar-mode~, ~tool-bar-mode~, ~tab-bar-mode~, and
~tab-line-mode~ when ~logos-focus-mode~ is enabled. If the given mode
is already disabled, the corresponding function does nothing.
Otherwise, it toggles the mode off/on when ~logos-focus-mode~ is
enabled/disabled.

#+begin_src emacs-lisp
(defun my-logos-hide-menu-bar ()
  (when logos-focus-mode
    (logos-set-mode-arg 'menu-bar-mode -1)))

(add-hook 'logos-focus-mode-hook #'my-logos-hide-menu-bar)

;; Assuming the `tool-bar-mode' is enabled by default...
(defun my-logos-hide-tool-bar ()
  (when logos-focus-mode
    (logos-set-mode-arg 'tool-bar-mode -1)))

(add-hook 'logos-focus-mode-hook #'my-logos-hide-tool-bar)

;; Assuming the `tab-bar-mode' is enabled by default...
(defun my-logos-hide-tab-bar ()
  (when logos-focus-mode
    (logos-set-mode-arg 'tab-bar-mode -1)))

(add-hook 'logos-focus-mode-hook #'my-logos-hide-tab-bar)

;; Assuming the `tab-line-mode' is enabled by default...
(defun my-logos-hide-tab-line ()
  (when logos-focus-mode
    (logos-set-mode-arg 'tab-line-mode -1)))

(add-hook 'logos-focus-mode-hook #'my-logos-hide-tab-line)
#+end_src

** Fixed a malformed ~cond~
:PROPERTIES:
:CUSTOM_ID: h:d420dabe-0d37-4ad0-a911-47a37dbaa3a4
:END:

This was affecting the ~logos-narrow-dwim~ function in some cases.
Thanks to Edgar Vincent for the contribution, which happened in the
now-defunct mailing list.

* 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: <https://github.com/protesilaos/logos/issues/12>.

* Version 1.0.0 on 2022-10-19
:PROPERTIES:
:CUSTOM_ID: h:b71866b6-393a-4bff-bb89-e52f5e2fca9d
:END:

+ 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
:PROPERTIES:
:CUSTOM_ID: h:189634ab-187a-4e44-9006-1361459150b8
:END:

+ 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:

  #+begin_src emacs-lisp
  (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))))
  #+end_src

+ 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:

  #+begin_quote
  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.
  #+end_quote

+ 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:

  #+begin_src emacs-lisp
  (setq shr-max-width fill-column)
  (setq shr-use-fonts nil)
  #+end_src

  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
:PROPERTIES:
:CUSTOM_ID: h:f0293274-8cde-4660-ba1a-cffce2910f2f
:END:

+ 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:

  + 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>

+ 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
:PROPERTIES:
:CUSTOM_ID: h:1c2f2cf0-7617-4bb6-9525-eafa1269d06f
:END:

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
:PROPERTIES:
:CUSTOM_ID: h:c7f4f53d-0397-4586-8b21-e9b26dddf6e9
:END:

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
:PROPERTIES:
:CUSTOM_ID: h:ca03557f-35c1-4342-b126-d08fd855dbf4
:END:

In the beginning, there was =prot-logos.el=.  A file that pieced
together some code and configurations I had for presentations (part of
[[https://gitlab.com/protesilaos/dotfiles][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.
