branch: externals/logos
commit 4a8270dbcb10703e414e5d5f820a52864a893052
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@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>.
