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

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

* 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.
