Fold and Focus — Focused navigation in Org, Markdown, and Elisp (Emacs package)

;;; fold-and-focus.el --- Focused navigation in Org, Markdown, and Elisp -*- lexical-binding: t -*-
;;; Commentary:
;;;; For all the details, please do see the README
;;; Acknowledgments:
;;; Code:
;;;; Libraries
;;;; Obsolete symbols
;;;; Symbols from other packages
;;;; Package metadata
;;;; Customizable variables
;;;; Functions
;;;;; Auxiliary
;;;;;; Maybe widen
;;;;;; Check whether valid mode
;;;;;; Check if first or last subtrees
;;;;; Core
;;;;;; Specific to Org
;;;;;; Specific to Markdown
;;;;;; Specific to Emacs Lisp
;;;;;; For all modes
;;;;; Navigation commands
;;;;;; by subtree: Emacs Lisp, Org, or Markdown
;;;;;; by defun: Emacs Lisp
;;;;; Minor modes
;;;;;; Auxiliary
;;;;;;; Parent keymaps
;;;;;; Org
;;;;;; Markdown
;;;;;; Emacs Lisp
;;;;; See README
;;;;; See News
;;;; Wrapping up
;;; fold-and-focus.el ends here

;;; fold-and-focus.el --- Focused navigation in Org, Markdown, and Elisp -*- lexical-binding: t -*-

;; SPDX-FileCopyrightText: © flandrew <https://flandrew.srht.site/listful>

;;---------------------------------------------------------------------------
;; Author:    flandrew
;; Created:   2021-06-11
;; Updated:   2025-06-15
;; Keywords:  outlines, convenience
;; Homepage:  <https://flandrew.srht.site/listful/software.html>
;;---------------------------------------------------------------------------
;; Package-Version:  1.3.0
;; Package-Requires: ((emacs "25.1"))
;;---------------------------------------------------------------------------

;; SPDX-License-Identifier: GPL-3.0-or-later

;; This file is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published
;; by the Free Software Foundation, either version 3 of the License,
;; or (at your option) any later version.
;;
;; This file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this file. If not, see <https://www.gnu.org/licenses/>.

;;; Commentary:
;;
;; Fold and Focus helps you navigate Org, Markdown and Emacs Lisp files with
;; focused attention: one thing at a time. You can navigate by heading or
;; by defun, optionally narrowing to it as you go.
;;
;; As you navigate, the heading you move to will be recentered, so you'll
;; always have it at a fixed position. Its contents will be shown.
;;
;; The heading you came from will be folded and won't distract you.
;;
;;;; For all the details, please do see the README
;;
;; Open it easily with:
;;   (find-file-read-only "README.org")   <--- C-x C-e here¹
;;
;; or from any buffer:
;;   M-x fold-and-focus-see-readme
;;
;; or read it online:
;;   <https://flandrew.srht.site/listful/sw-emacs-fold-and-focus.html>
;;
;; ¹ or the key that ‘eval-last-sexp’ is bound to, if not C-x C-e.
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;;; Acknowledgments:
;;
;; Outshine's ‘outshine-narrow-to-subtree’ was borrowed and simplified to
;; create the functions ‘fold-and-focus-fancy-narrow-to-el-subtree’ and
;; ‘fold-and-focus-narrow-to-el-subtree’.
;;
;; outshine
;;   SPDX-FileCopyrightText:  © Thorsten Jolitz and contributors
;;   SPDX-License-Identifier: GPL-2.0-or-later
;;   Author:                  Thorsten Jolitz
;;   Homepage:                <https://github.com/alphapapa/outshine>
;;
;; ------------------------------------------------------------------------
;;
;; An older version of ‘org-narrow-to-subtree’ has been adapted to create the
;; function ‘fold-and-focus-fancy-narrow-to-org-subtree’, which in turn was
;; used for ‘fold-and-focus-fancy-narrow-to-md-subtree’, which adapts it to
;; markdown. (The org function is a bit different from the one used by the
;; fancy-narrow package, which copied it from ‘org-narrow-to-subtree’.)
;;
;; org
;;   SPDX-FileCopyrightText:  © Free Software Foundation, Inc.
;;   SPDX-License-Identifier: GPL-3.0-or-later
;;   Author:                  Carsten Dominik
;;   Homepage:                <https://orgmode.org>
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;



;;; Code:
;;;; Libraries

(require 'outline)
(require 'lisp-mnt)  ; ‘lm-summary’, ‘lm-homepage’, ‘lm-version’, ‘lm-header’


;;;; Obsolete symbols

(define-obsolete-function-alias
  'fold-and-focus-fancy-narrow-to-subtree
  'fold-and-focus-fancy-narrow-to-el-subtree "1.1.0")
(define-obsolete-function-alias
  'fold-and-focus-fold-and-show-children
  'fold-and-focus-widen-maybe-and-hide       "1.3.0")
(define-obsolete-function-alias
  'fold-and-focus-fold-and-read-previous-entry
  'fold-and-focus-go-read-previous-entry     "1.3.0")
(define-obsolete-function-alias
  'fold-and-focus-fold-and-read-next-entry
  'fold-and-focus-go-read-next-entry         "1.3.0")


;;;; Symbols from other packages

;; Silence "not known to be defined" compiler warnings
(declare-function fancy-narrow-to-region     "ext:fancy-narrow" (start end))
(declare-function fancy-widen                "ext:fancy-narrow" ())
(declare-function markdown-back-to-heading   "ext:markdown")
(declare-function markdown-end-of-subtree    "ext:markdown")
(declare-function markdown-heading-at-point  "ext:markdown")
(declare-function org-at-heading-p           "ext:org")
(declare-function org-back-to-heading        "ext:org")
(declare-function org-end-of-subtree         "ext:org")


;;;; Package metadata

(defvar fold-and-focus--name "Fold and Focus")

(defvar fold-and-focus--dot-el
  (format "%s.el" (file-name-sans-extension (eval-and-compile
                                              (or load-file-name
                                                  buffer-file-name)))))
(defvar fold-and-focus--readme-org
  (expand-file-name "README.org" (file-name-directory fold-and-focus--dot-el)))

(defvar fold-and-focus--summary  (lm-summary   fold-and-focus--dot-el))
(defvar fold-and-focus--homepage (lm-homepage  fold-and-focus--dot-el))
(defvar fold-and-focus--version  (lm-with-file fold-and-focus--dot-el
                                   (or (lm-header "package-version")
                                       (lm-version))))


;;;; Customizable variables

(defgroup fold-and-focus nil
  (format "%s." fold-and-focus--summary)
  :group 'convenience
  :link  '(emacs-library-link :tag "Lisp file" "fold-and-focus.el")
  :link  `(file-link :tag "README.org" ,fold-and-focus--readme-org)
  :link  `(url-link  :tag "Homepage"   ,fold-and-focus--homepage))

(defcustom fold-and-focus-recenter-position 2
  "Number of lines from the top of the window where focused headings will be.
It uses ‘recenter-top-bottom’, so a negative number will be interpreted as
number of lines from the bottom of the window."
  :package-version '(fold-and-focus "1.0.0")
  :type 'integer)


;;;; Functions
;;;;; Auxiliary
;;;;;; Maybe widen

(defun fold-and-focus-reg-widen-maybe ()
  "Decide whether to widen."
  (when (buffer-narrowed-p)
    (if (fboundp 'recursive-widen)
        (recursive-widen)
      (widen))))

(defun fold-and-focus-fancy-widen-maybe ()
  "Decide whether to ‘fancy-widen’."
  (and (fboundp 'fancy-narrow-active-p)
       (fancy-narrow-active-p)
       (fancy-widen)))


;;;;;; Check whether valid mode

(defun fold-and-focus-check-my-mode (&optional function-name)
  "Check whether fold-and-focus will work in this mode.
Optionally, give a FUNCTION-NAME in the error message."
  (or (derived-mode-p 'org-mode)
      (derived-mode-p 'markdown-mode)
      (derived-mode-p 'emacs-lisp-mode)
      (user-error (concat "To use %s, your mode must be "
                          "org, markdown, emacs-lisp, or "
                          "derived from them")
                  (or function-name "this command"))))


;;;;;; Check if first or last subtrees

(defun fold-and-focus--find-heading (count)
  "Search COUNT headings forwards, or return nil."
  (re-search-forward
   (format "^\\(?:%s\\)" outline-regexp)
   nil t count))

(defun fold-and-focus--before-1st-p ()
  "Is this before the first heading?"
  (save-excursion
    (goto-char (line-end-position))
    (null (fold-and-focus--find-heading -1))))

(defun fold-and-focus--1st-p ()
  "Is this the first subtree?"
  (save-excursion
    (goto-char (line-end-position))
    (when (fold-and-focus--find-heading -1)
      (null (fold-and-focus--find-heading -1)))))

(defun fold-and-focus--last-p ()
  "Is this the last subtree?"
  (save-excursion
    (goto-char (line-end-position))
    (null (fold-and-focus--find-heading 1))))


;;;;; Core
;;;;;; Specific to Org

(defun fold-and-focus-fancy-narrow-to-org-subtree ()
  "Fancy-narrow to the current org subtree.
Use the command `\\[fancy-widen]' to see the whole buffer again."
  (interactive)
  (save-excursion
    (save-match-data
      (fancy-narrow-to-region
       (progn (org-back-to-heading t) (point))
       (progn (org-end-of-subtree t t)
              (and (org-at-heading-p)
                   (not (eobp))
                   (backward-char 1))
              (point))))))

(defun fold-and-focus--read-entry-org (&optional narrow-option)
  "Focus on Org entry to read it.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (pcase narrow-option
    (:reg   (when (fboundp 'org-narrow-to-subtree)
              (if (fboundp 'recursive-narrow-or-widen-dwim)
                  (recursive-narrow-or-widen-dwim)
                (org-narrow-to-subtree))))
    (:fancy (when (fboundp 'fancy-narrow-to-region)
              (fold-and-focus-fancy-narrow-to-org-subtree))))
  (unless (bound-and-true-p org-sticky-header-mode)
    (when (fboundp 'org-display-outline-path)
      (org-display-outline-path))))


;;;;;; Specific to Markdown

(defun fold-and-focus-fancy-narrow-to-md-subtree ()
  "Fancy-narrow to the current markdown subtree.
Use the command `\\[fancy-widen]' to see the whole buffer again."
  (interactive)
  (save-excursion
    (save-match-data
      (fancy-narrow-to-region
       (progn (markdown-back-to-heading t) (point))
       (progn (markdown-end-of-subtree t)
              (and (markdown-heading-at-point)
                   (not (eobp))
                   (backward-char 1))
              (point))))))

(defun fold-and-focus--read-entry-md (&optional narrow-option)
  "Focus on Markdown entry to read it.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (pcase narrow-option
    (:reg   (when (fboundp 'markdown-narrow-to-subtree)
              (if (fboundp 'recursive-narrow-save-position)
                  (recursive-narrow-save-position
                   (markdown-narrow-to-subtree))
                (markdown-narrow-to-subtree))))
    (:fancy (when (fboundp 'fancy-narrow-to-region)
              (fold-and-focus-fancy-narrow-to-md-subtree)))))


;;;;;; Specific to Emacs Lisp

(defun fold-and-focus-narrow-to-el-subtree ()
  "Narrow to the current elisp comments subtree.
Use the command ‘\\[widen]’ to see the whole buffer again."
  (interactive)
  (outline-mark-subtree)
  (when (use-region-p)
    (narrow-to-region (region-beginning) (region-end)))
  (deactivate-mark))

(defun fold-and-focus-fancy-narrow-to-el-subtree ()
  "Fancy-narrow to the current elisp comments subtree.
Use the command ‘\\[fancy-widen]’ to see the whole buffer again."
  (interactive)
  (outline-mark-subtree)
  (when (use-region-p)
    (fancy-narrow-to-region (region-beginning) (region-end)))
  (deactivate-mark))

(defun fold-and-focus--read-entry-el (&optional narrow-option)
  "Focus on Emacs Lisp entry to read it.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (pcase narrow-option
    (:reg   (fold-and-focus-narrow-to-el-subtree))
    (:fancy (when (fboundp 'fancy-narrow-to-region)
              (fold-and-focus-fancy-narrow-to-el-subtree)))))

(defun fold-and-focus-read-defun (&optional narrow-option)
  "In Emacs Lisp mode, focus on defun to read it.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (recenter-top-bottom fold-and-focus-recenter-position)
  (pcase narrow-option
    (:reg   (if (fboundp 'recursive-narrow-to-defun)
                (recursive-narrow-to-defun)
              (narrow-to-defun)))
    (:fancy (when (fboundp 'fancy-narrow-to-defun)
              (fancy-narrow-to-defun)))))

(defun fold-and-focus-read--goto-defun (e b &optional narrow-option)
  "Go to defun ending in E and beginning in B.
If NARROW-OPTION is :reg, try to widen first."
  (fold-and-focus-fancy-widen-maybe)
  (pcase narrow-option
    (:reg (fold-and-focus-reg-widen-maybe)))
  (end-of-defun e)
  (beginning-of-defun b)
  (when (outline-invisible-p)
    (outline-show-entry)
    (end-of-defun e)
    (beginning-of-defun b))
  (fold-and-focus-read-defun narrow-option))


;;;;;; For all modes

(defun fold-and-focus-widen-maybe-and-hide (&optional narrow-option)
  "Fold and show children.
If NARROW-OPTION is :reg, try to widen first."
  (fold-and-focus-fancy-widen-maybe)
  (pcase narrow-option
    (:reg (fold-and-focus-reg-widen-maybe)))
  (outline-back-to-heading)
  (outline-hide-subtree))

(defun fold-and-focus-read-entry (&optional narrow-option)
  "Focus on entry to read it.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (outline-hide-subtree)
  (outline-show-children)
  (outline-show-entry)
  (recenter-top-bottom fold-and-focus-recenter-position)
  (cond ((derived-mode-p 'org-mode)
         (fold-and-focus--read-entry-org narrow-option))
        ((derived-mode-p 'markdown-mode)
         (fold-and-focus--read-entry-md  narrow-option))
        ((derived-mode-p 'emacs-lisp-mode)
         (fold-and-focus--read-entry-el  narrow-option))))

(defun fold-and-focus-go-read-previous-entry (&optional narrow-option)
  "Go read previous entry.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (if (fold-and-focus--before-1st-p)
      (message "Before first heading")
    (fold-and-focus-widen-maybe-and-hide narrow-option)
    (if (fold-and-focus--1st-p)
      (message "No previous subtree")
      (outline-previous-visible-heading 1)
      (fold-and-focus-read-entry narrow-option))))

(defun fold-and-focus-go-read-next-entry (&optional narrow-option)
  "Go read next entry.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (if (fold-and-focus--before-1st-p)
      (progn (outline-next-visible-heading 1)
             (fold-and-focus-read-entry narrow-option))
    (fold-and-focus-widen-maybe-and-hide narrow-option)
    (if (fold-and-focus--last-p)
        (message "No next subtree")
      (outline-show-children)
      (outline-next-visible-heading 1)
      (fold-and-focus-read-entry narrow-option))))


;;;;; Navigation commands
;;;;;; by subtree: Emacs Lisp, Org, or Markdown

;;;###autoload
(defun fold-and-focus-previous ()
  "Fold all, read previous entry. No further narrowing."
  (interactive)
  (fold-and-focus-check-my-mode this-command)
  (fold-and-focus-go-read-previous-entry))

;;;###autoload
(defun fold-and-focus-next ()
  "Fold all, read next entry. No further narrowing."
  (interactive)
  (fold-and-focus-check-my-mode this-command)
  (fold-and-focus-go-read-next-entry))

;;;###autoload
(defun fold-and-focus-previous-reg ()
  "Fold all, read previous entry.
Narrow to it (recursively, if possible)."
  (interactive)
  (fold-and-focus-check-my-mode this-command)
  (fold-and-focus-go-read-previous-entry :reg))

;;;###autoload
(defun fold-and-focus-next-reg ()
  "Fold all, read next entry.
Narrow to it (recursively, if possible)."
  (interactive)
  (fold-and-focus-check-my-mode this-command)
  (fold-and-focus-go-read-next-entry :reg))

;;;###autoload
(defun fold-and-focus-previous-fancy ()
  "Fold all, read previous entry. Fancy-narrow to it."
  (interactive)
  (fold-and-focus-check-my-mode this-command)
  (fold-and-focus-go-read-previous-entry :fancy))

;;;###autoload
(defun fold-and-focus-next-fancy ()
  "Fold all, read next entry. Fancy-narrow to it."
  (interactive)
  (fold-and-focus-check-my-mode this-command)
  (fold-and-focus-go-read-next-entry :fancy))


;;;;;; by defun: Emacs Lisp

;;;###autoload
(defun fold-and-focus-read-previous-defun (&optional narrow-option)
  "In Emacs Lisp mode, move to the beginning of the previous defun.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (interactive)
  (fold-and-focus-read--goto-defun 1 2 narrow-option))

;;;###autoload
(defun fold-and-focus-read-next-defun (&optional narrow-option)
  "In Emacs Lisp mode, move to the beginning of the next defun.
If NARROW-OPTION is :reg or :fancy, narrow accordingly."
  (interactive)
  (fold-and-focus-read--goto-defun 2 1 narrow-option))

;;;###autoload
(defun fold-and-focus-read-previous-defun-reg ()
  "In Emacs Lisp mode, narrow to the beginning of the previous defun."
  (interactive)
  (fold-and-focus-read--goto-defun 1 2 :reg))

;;;###autoload
(defun fold-and-focus-read-next-defun-reg ()
  "In Emacs Lisp mode, narrow to the beginning of the next defun."
  (interactive)
  (fold-and-focus-read--goto-defun 2 1 :reg))

;;;###autoload
(defun fold-and-focus-read-previous-defun-fancy ()
  "In Emacs Lisp mode, fancy-narrow to the beginning of the previous defun."
  (interactive)
  (fold-and-focus-read--goto-defun 1 2 :fancy))

;;;###autoload
(defun fold-and-focus-read-next-defun-fancy ()
  "In Emacs Lisp mode, fancy-narrow to the beginning of the next defun."
  (interactive)
  (fold-and-focus-read--goto-defun 2 1 :fancy))


;;;;; Minor modes
;;;;;; Auxiliary
;;;;;;; Parent keymaps

(defvar fold-and-focus-subtree-nav-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "M-[")  #'fold-and-focus-previous)
    (define-key map (kbd "M-]")  #'fold-and-focus-next)
    (define-key map (kbd "s-{")  #'fold-and-focus-previous-reg)
    (define-key map (kbd "s-}")  #'fold-and-focus-next-reg)
    (define-key map (kbd "s-[")  #'fold-and-focus-previous-fancy)
    (define-key map (kbd "s-]")  #'fold-and-focus-next-fancy)
    map)
  "Keymap for subtree navigation.")

(defvar fold-and-focus-defun-nav-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "s-.")  #'fold-and-focus-read-previous-defun)
    (define-key map (kbd "s-/")  #'fold-and-focus-read-next-defun)
    (define-key map (kbd "s-:")  #'fold-and-focus-read-previous-defun-reg)
    (define-key map (kbd "s-\"") #'fold-and-focus-read-next-defun-reg)
    (define-key map (kbd "s-;")  #'fold-and-focus-read-previous-defun-fancy)
    (define-key map (kbd "s-'")  #'fold-and-focus-read-next-defun-fancy)
    map)
  "Keymap for defun navigation.")


;;;;;; Org

(defvar fold-and-focus-org-mode-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map fold-and-focus-subtree-nav-map)
    map)
  "Keymap for Org mode navigation.")

(defcustom fold-and-focus-org-mode-lighter " ⏿o"
  "Mode line lighter for ‘fold-and-focus-org-mode’.
Either a string to display in the mode line when
‘fold-and-focus-org-mode’ is on, or nil to display nothing."
  :package-version '(fold-and-focus "1.2.0")
  :type '(choice (string :tag "Lighter" :value " ⏿o")
                 (const  :tag "Nothing" nil)))

;;;###autoload
(define-minor-mode fold-and-focus-org-mode
  "Enable keys for ‘fold-and-focus’ in ‘org-mode’ or derived.
See also ‘fold-and-focus-org-mode-lighter’ and
‘global-fold-and-focus-org-mode’."
  :init-value nil
  :lighter fold-and-focus-org-mode-lighter
  :keymap  fold-and-focus-org-mode-map)

(defun fold-and-focus--turn-on-org-mode ()
  "Enable ‘fold-and-focus-org-mode’ globally."
  (when (derived-mode-p 'org-mode)
    (fold-and-focus-org-mode)))

;;;###autoload
(define-globalized-minor-mode global-fold-and-focus-org-mode
  fold-and-focus-org-mode  fold-and-focus--turn-on-org-mode)


;;;;;; Markdown

(defvar fold-and-focus-md-mode-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map fold-and-focus-subtree-nav-map)
    map)
  "Keymap for Markdown mode navigation.")

(defcustom fold-and-focus-md-mode-lighter " ⏿m"
  "Mode line lighter for ‘fold-and-focus-md-mode’.
Either a string to display in the mode line when
‘fold-and-focus-md-mode’ is on, or nil to display nothing."
  :package-version '(fold-and-focus "1.2.0")
  :type '(choice (string :tag "Lighter" :value " ⏿m")
                 (const  :tag "Nothing" nil)))

;;;###autoload
(define-minor-mode fold-and-focus-md-mode
  "Enable keys for ‘fold-and-focus’ in ‘markdown-mode’ or derived.
See also ‘fold-and-focus-md-mode-lighter’ and
‘global-fold-and-focus-md-mode’."
  :init-value nil
  :lighter fold-and-focus-md-mode-lighter
  :keymap  fold-and-focus-md-mode-map)

(defun fold-and-focus--turn-on-md-mode ()
  "Enable ‘fold-and-focus-md-mode’ globally."
  (when (derived-mode-p 'markdown-mode)
    (fold-and-focus-md-mode)))

;;;###autoload
(define-globalized-minor-mode global-fold-and-focus-md-mode
  fold-and-focus-md-mode  fold-and-focus--turn-on-md-mode)


;;;;;; Emacs Lisp

(defvar fold-and-focus-el-mode-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent
     map (make-composed-keymap
          fold-and-focus-defun-nav-map
          fold-and-focus-subtree-nav-map))
    map)
  "Keymap for Emacs Lisp mode navigation.")

(defcustom fold-and-focus-el-mode-lighter " ⏿e"
  "Mode line lighter for ‘fold-and-focus-el-mode’.
Either a string to display in the mode line when
‘fold-and-focus-el-mode’ is on, or nil to display nothing."
  :package-version '(fold-and-focus "1.2.0")
  :type '(choice (string :tag "Lighter" :value " ⏿e")
                 (const  :tag "Nothing" nil)))

;;;###autoload
(define-minor-mode fold-and-focus-el-mode
  "Enable keys for ‘fold-and-focus’ in ‘emacs-lisp-mode’ or derived.
See also ‘fold-and-focus-el-mode-lighter’ and
‘global-fold-and-focus-el-mode’."
  :init-value nil
  :lighter fold-and-focus-el-mode-lighter
  :keymap  fold-and-focus-el-mode-map)

(defun fold-and-focus--turn-on-el-mode ()
  "Enable ‘fold-and-focus-el-mode’ globally."
  (when (derived-mode-p 'emacs-lisp-mode)
    (fold-and-focus-el-mode)))

;;;###autoload
(define-globalized-minor-mode global-fold-and-focus-el-mode
  fold-and-focus-el-mode  fold-and-focus--turn-on-el-mode)


;;;;; See README

;;;###autoload
(defun fold-and-focus-see-readme (&optional heading narrow)
  "Open fold-and-focus's README.org file.
Search for the file in fold-and-focus.el's directory.

If found, open it read-only.

If optional argument HEADING is passed, try to navigate to the
heading after opening it. HEADING should be a string.

If optional argument NARROW is non-nil, narrow to that heading.
This argument has no effect if HEADING is nil or not found."
  (interactive)
  (let ((readme fold-and-focus--readme-org))
    (if (file-exists-p readme)
        (let ((pr (make-progress-reporter
                   (format "Opening %s ... "
                           (abbreviate-file-name readme)))))
          (find-file-read-only readme)
          (when heading
            (fold-and-focus--goto-org-heading heading narrow))
          (progress-reporter-done pr))
      (message "Couldn't find %s's README.org" fold-and-focus--name))))

(defun fold-and-focus--goto-org-heading (heading &optional narrow)
  "Navigate to org HEADING and optionally NARROW to it."
  (let* ((hrx (format "^[*]+ %s" heading))
         (pos (save-match-data
                (save-excursion
                  (save-restriction
                    (widen)
                    (goto-char (point-max))
                    (re-search-backward hrx nil t 1))))))
    (when pos
      (widen)
      (goto-char pos)
      (if (and narrow (fboundp 'org-narrow-to-subtree))
          (org-narrow-to-subtree)
        (recenter-top-bottom 1))
      (when (fboundp 'outline-show-subtree)
        (outline-show-subtree))
      (when (fboundp 'org-flag-drawer)
        (save-excursion
          (forward-line 1)
          (org-flag-drawer t))))))


;;;;; See News

;;;###autoload
(defun fold-and-focus-see-news ()
  "See the News in fold-and-focus's README.org file."
  (interactive)
  (fold-and-focus-see-readme "News" 'narrow)
  (fold-and-focus--display-org-subtree))

(defun fold-and-focus--display-org-subtree ()
  "Selectively display org subtree."
  (let ((cmds '(outline-hide-subtree
                outline-show-children
                outline-next-heading
                outline-show-branches)))
    (and (fboundp (nth 0 cmds))
         (fboundp (nth 1 cmds))
         (fboundp (nth 2 cmds))
         (fboundp (nth 3 cmds))
         (mapc #'funcall cmds))))


;;;; Wrapping up

(provide 'fold-and-focus)

;; Local Variables:
;; coding:                     utf-8
;; indent-tabs-mode:           nil
;; sentence-end-double-space:  nil
;; outline-regexp:             ";;;;* "
;; End:

;;; fold-and-focus.el ends here