[elpa] externals/logos 4a8270dbcb 4/4: Update package Commentary

[ELPA Syncer]

branch: externals/logos
commit 4a8270dbcb10703e414e5d5f820a52864a893052
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Update package Commentary
---
 logos.el | 60 ++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 42 insertions(+), 18 deletions(-)

diff --git a/logos.el b/logos.el
index 24f8a5836e..a05182200c 100644
--- a/logos.el
+++ b/logos.el
@@ -27,39 +27,63 @@
 
 ;;; Commentary:
 ;;
-;; This package provides a simple "focus mode" which can be applied to
-;; any buffer for reading, writing, or even doing a presentation.  The
-;; buffer can be divided in pages using the `page-delimiter', outline
-;; structure, or any other pattern.  Commands are provided to move
-;; between those pages.  These motions work even when narrowing is in
-;; effect (and they preserve it).  `logos.el' is designed to be simple
-;; by default and easy to extend.  This manual provides concrete
-;; examples to that end.
+;; This package provides a simple "focus mode" which can be applied to any
+;; buffer for reading, writing, or even doing a presentation.  The buffer
+;; can be divided in pages using the `page-delimiter', outline structure,
+;; or any other pattern.  Commands are provided to move between those
+;; pages.  These motions work even when narrowing is in effect (and they
+;; preserve it).  `logos.el' is designed to be simple by default and easy
+;; to extend.  This manual provides concrete examples to that end.
 ;;
-;; Logos does not define any key bindings.  Try something like this:
+;; What constitutes a page delimiter is determined by the user options
+;; `logos-outlines-are-pages' and `logos-outline-regexp-alist'.  By
+;; default, this only corresponds to the `^L' character (which can be
+;; inserted using the standard keys with `C-q C-l').
+;;
+;; Logos does not define any key bindings.  Try something like this, if you
+;; want:
 ;;
 ;;     (let ((map global-map))
 ;;       (define-key map [remap narrow-to-region] #'logos-narrow-dwim)
 ;;       (define-key map [remap forward-page] #'logos-forward-page-dwim)
 ;;       (define-key map [remap backward-page] #'logos-backward-page-dwim))
 ;;
-;; By default those key bindings are: C-x n n, C-x ], C-x [.
+;; On standard Emacs, those key bindings are: `C-x n n', `C-x ]', `C-x ['.
+;; The `logos-narrow-dwim' is not necessary for users who already know how
+;; to narrow effectively.  Such users may still want to bind it to a key.
+;;
+;; For users running Emacs version 28 or higher, Logos defines the
+;; `logos-repeat-map' which is activated when `repeat-mode' is enabled.
+;; This means that page motions, `C-x ]' and `C-x [', can be repeated by
+;; following them up with `]' and `[', respectively.  The repetition stops
+;; when another command is invoked.
 ;;
-;; The `logos-focus-mode' tweaks the aesthetics of the current buffer.
-;; When enabled it sets the buffer-local value of these user options:
-;; `logos-scroll-lock', `logos-variable-pitch',`logos-hide-mode-line',
-;; `logos-hide-buffer-boundaries', `logos-buffer-read-only',
-;; `logos-olivetti', and `logos-hide-fringe'.
+;; Logos provides some optional aesthetic tweaks which come into effect
+;; when the buffer-local `logos-focus-mode' is enabled.  These will hide
+;; the mode line (`logos-hide-mode-line'), disable the buffer boundary
+;; indicators (`indicate-buffer-boundaries'), enable `scroll-lock-mode'
+;; (`logos-scroll-lock'), use `variable-pitch-mode' in non-programming
+;; buffers (`logos-variable-pitch'), make the buffer read-only
+;; (`logos-buffer-read-only'), center the buffer in its window if the
+;; `olivetti' package is installed (`logos-olivetti'), and hide the
+;; `fringe' face (`logos-hide-fringe').  All these variables are
+;; buffer-local.
 ;;
-;; Logos is the familiar word derived from Greek (watch my presentation
-;; on philosophy about Cosmos, Logos, and the living universe:
+;; Furthermore, the `logos-focus-mode' establishes a bespoke keymap, which
+;; can be used to, for example, bind the arrow keys to page motions.  The
+;; keymap is `logos-focus-mode-map' and is empty by default (we do not
+;; define any keys and trust the user to pick their own).
+;;
+;; Logos is the familiar word derived from Greek (watch my presentation on
+;; philosophy about Cosmos, Logos, and the living universe:
 ;; <https://protesilaos.com/books/2022-02-05-cosmos-logos-living-universe/>),
 ;; though it also stands for these two perhaps equally insightful
 ;; backronyms about the mechanics of this package:
 ;;
-;; 1. ^L Only Generates Ostensible Slides
+;; 1. `^L' Only Generates Ostensible Slides
 ;; 2. Logos Optionally Garners Outline Sections
 ;;
+;;
 ;; Consult the manual for all sorts of tweaks and extras:
 ;; <https://protesilaos.com/emacs/logos>.