From 4704bed4ae83f8ff7aa8fc218f64412627d5b35d Mon Sep 17 00:00:00 2001
From: Eshel Yaron <eshel@dazz.io>
Date: Sat, 18 Jun 2022 00:08:25 +0300
Subject: [PATCH] Document elisp blocks in Presentation mode section

---
 .emacs.d/esy.org | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/.emacs.d/esy.org b/.emacs.d/esy.org
index 12eb862..1e922db 100644
--- a/.emacs.d/esy.org
+++ b/.emacs.d/esy.org
@@ -1450,31 +1450,37 @@ without asking each time.
 :END:
 #+begin_src emacs-lisp
   (defun org-present-forward-heading-same-level (arg)
+    "Widen, move forward ARG headings, and narrow to subtree."
     (interactive "p" org-mode)
     (org-present-widen-and-narrow #'org-forward-heading-same-level
                                   `(,arg t)))
 
   (defun org-present-backward-heading-same-level (arg)
+    "Widen, move backward ARG headings, and narrow to subtree."
     (interactive "p" org-mode)
     (org-present-widen-and-narrow #'org-backward-heading-same-level
                                   `(,arg t)))
 
   (defun org-present-next-visible-heading (arg)
+    "Widen, move to the next ARG'th heading, and narrow to subtree."
     (interactive "p" org-mode)
     (org-present-widen-and-narrow #'org-next-visible-heading
                                   `(,arg)))
 
   (defun org-present-previous-visible-heading (arg)
+    "Widen, move to the previous ARG'th heading, and narrow to subtree."
     (interactive "p" org-mode)
     (org-present-widen-and-narrow #'org-previous-visible-heading
                                   `(,arg)))
 
   (defun org-present-up-heading (arg)
+    "Widen, move up ARG'th headings, and narrow to subtree."
     (interactive "p" org-mode)
     (org-present-widen-and-narrow #'outline-up-heading
                                   `(,arg t)))
 
   (defun org-present-widen-and-narrow (f args)
+    "Widen, apply F to ARGS, narrow to subtree and adjust visibility."
     (widen)
     (apply f args)
     (org-narrow-to-subtree)
@@ -1484,7 +1490,22 @@ without asking each time.
     (org-show-children))
 
   (define-minor-mode org-present-mode
-    "Minor mode for automatic widening and narrowing in Org mode."
+    "Minor mode for seamlessly widening and narrowing in `org-mode'.
+  When `org-present-mode' is enabled is a buffer, it remaps several
+  keybindings which normally invoke common commands that move point
+  from one heading to another to, invoke equivalent commands with
+  the sole change of widening before applying the command, and
+  narrowing to the target subtree after it.  This allows for
+  presenting Org mode files one heading at a time, by narrowing and
+  moving freely between headings like presentation slides, without
+  the need to explicitly use `\\[widen]' followed by
+  '\\[org-narrow-to-subtree]' in another heading.
+
+  The commands currenlty remapped by `org-present-mode' are
+  `\\[org-forward-heading-same-level]',
+  `\\[org-backward-heading-same-level]',
+  `\\[org-next-visible-heading]',
+  `\\[org-previous-visible-heading]' and `\\[outline-up-heading]'."
     :init-value nil
     :keymap '(([ remap org-forward-heading-same-level   ]
                . org-present-forward-heading-same-level )
@@ -1508,6 +1529,9 @@ without asking each time.
 :END:
 #+begin_src emacs-lisp
   (defun esy/logos-focus ()
+    "Toggle settings for focused display with `logus-focus-mode'.
+  This function in intended to be used as a member of
+  `logos-focus-mode-extra-functions'."
     (when (eq major-mode 'org-mode)
       (org-show-all)
       (logos--mode 'org-present-mode 1)
@@ -1538,6 +1562,7 @@ without asking each time.
     (add-hook 'logos-focus-mode-extra-functions #'delete-other-windows))
 
   (defun esy/present-buffer ()
+    "Toggle `logos-focus-mode' in the current buffer."
     (interactive)
     (require 'outline)
     (require 'logos)
-- 
2.39.5