Fix headings and docs to conform to elisp standard

bible.el

@@ -1,15 +1,28 @@
-;;; -*- mode: EMACS-LISP; lexical-binding: t -*-
+;;; bible.el --- A Bible browsing application -*- lexical-binding: t; mode: EMACS-LISP; -*-
 
-;;
-;; bible.el --- A browsing interface for the SWORD Project's Diatheke CLI
-;;
-;; Copyright (c) 2025 Fred Gilham
+;; Copyright (c) 2025-2026 Fred Gilham
 
-;; Author: Fred Gilham
-;; URL: https://gitbot.homedns.org/fred/bible-mode
+;; Author: Fred Gilham <fmgilham@gmail.com>
 ;; Version: 1.0.0
 ;; Keywords: files, text, hypermedia
-;; Package-Requires: ((emacs "29.1"))
+;; Package-Requires: ((emacs "29.1") cl-lib dom shr)
+;; URL: https://gitbot.homedns.org/fred/bible-mode
+
+;; This file is not part of GNU Emacs.
+
+;; bible.el 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, or (at your option)
+;; any later version.
+
+;; bible.el 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; see the file LICENSE. If not, see
+;; <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
 
@@ -20,7 +33,7 @@
 ;; Biblical texts provided by the Sword project.
 ;; Word study is also supported.
 
-;;; Usage:
+;;;; Usage
 
 ;; Use M-x `bible-open' to open a Bible buffer.
 ;; Use C-h f `bible' to see available keybindings.
@@ -31,7 +44,7 @@
 ;; module, as well as `bible-word-study-enabled' to enable word
 ;; study by default.
 
-;;; Design:
+;;;; Design
 
 ;; The idea here is to use the diatheke program to insert text from
 ;; modules into buffers. The main bible display uses an "internal" XML
@@ -54,6 +67,8 @@
 
 ;;; Code:
 
+;;;; Environment stuff
+
 ;; Turn off tool bar mode because we are greedy for pixels....
 (tool-bar-mode -1)
 ;; eldoc isn't meaningful in this program, and this saves space in the
@@ -66,9 +81,11 @@
 (require 'dom)
 (require 'shr)
 
-  
-;;; dom-text and dom-texts declared obsolescent in emacs 31. check for
-;;; new function, retain backward compatibility.
+
+;;;; Aliases for obsolete functions
+
+;; dom-text and dom-texts declared obsolescent in emacs 31. check for
+;; new function, retain backward compatibility.
 (defalias 'bible-dom-text
   (if (fboundp 'dom-inner-text)
       (lambda (node)
@@ -86,7 +103,7 @@
 	(dom-texts node)))))
 
 
-;;;; Variables
+;;;; Configuration Variables
 
 (defgroup bible nil
   "Settings for `bible'."
@@ -102,8 +119,8 @@ modules, run `diatheke -b system -l bibliography')"
 ;;  :local t
   :group 'bible)
 
-;;;
-;;; XXX Not implememted yet
+;;
+;; XXX Not implememted yet
 (defcustom bible-font
   "Ezra SIL"
   "Default font for bible (not yet implemented)."
@@ -159,9 +176,9 @@ which are of the form
   :group 'bible)
 
 
-;;; XXX The Hebrew lexicons differ on whether they accept keys of the
-;;; form `Hnnnn' or `nnnn'. The code does not yet handle this
-;;; correctly, so stick with the following.
+;; XXX The Hebrew lexicons differ on whether they accept keys of the
+;; form `Hnnnn' or `nnnn'. The code does not yet handle this
+;; correctly, so stick with the following.
 (defcustom bible-hebrew-lexicon
   "BDBGlosses_Strongs" ; This seems to work
   "Lexicon used for displaying definitions of Hebrew words using Strong's
@@ -201,7 +218,7 @@ bible--display-lemma-hebrew."
   :local nil
   :group 'bible)
 
-;;; variable defs
+;;;; Variable definitions
 
 (defconst bible--verse-regexp "\\(I \\|1 \\|II \\|2 \\|III \\|3 \\)??[a-zA-Z]+?[ \t\n][0-9]+[:][0-9]+")
 
@@ -285,7 +302,7 @@ bible--display-lemma-hebrew."
     ("Re"   . "Revelation of John") ("Rev"   . "Revelation of John"))
   "A-list of abbreviations for Bible books.")
 
-;;;; Book / chapter
+;;;;; Book / chapter
 
 (defvar-local bible--current-book (assoc "Genesis" bible--books)
   "Current book data (name . chapter).")
@@ -312,8 +329,8 @@ bible--display-lemma-hebrew."
 
 ;;;; Keymaps
 
-;;;; N.B. Bible menu items appear in reverse order of their
-;;;; definition below
+;; N.B. Bible menu items appear in reverse order of their definition
+;; below
 
 (defconst bible-map (make-sparse-keymap)
   "Keymap for bible.")
@@ -324,11 +341,6 @@ bible--display-lemma-hebrew."
 	    [menu-bar bible toggle-debug]
 	    '("Toggle debug-on-error" . toggle-debug-on-error))
 
-(defun bible-toggle-display-diatheke ()
-  "Toggle diatheke args display."
-  (interactive)
-  (setq bible-show-diatheke-exec (not bible-show-diatheke-exec))
-  (message ""))
 
 (define-key bible-map
 	    [menu-bar bible display-diatheke]
@@ -337,12 +349,6 @@ bible--display-lemma-hebrew."
 (defvar-local bible-debugme nil
   "Make text show up as XML when set.")
 
-(defun bible-toggle-display-xml ()
-  "Toggle XML display."
-  (interactive)
-  (setq-local bible-debugme (not bible-debugme))
-  (bible--display))
-
 (define-key bible-map "d" 'bible-toggle-display-xml)
 (define-key bible-map
 	    [menu-bar bible display-xml]
@@ -352,7 +358,8 @@ bible--display-lemma-hebrew."
 	    [menu-bar bible sep]
 	    '(menu-item '"--"))
 
-;;;;; Misc
+;;;;; Misc key bindings
+
 (define-key bible-map "m" 'bible-select-module)
 (define-key bible-map "w" 'bible-toggle-word-study)
 (define-key bible-map "l" 'bible-toggle-red-letter)
@@ -374,6 +381,18 @@ bible--display-lemma-hebrew."
 	    [menu-bar bible range]
 	    '("Set Search Range" . bible-set-search-range))
 
+(defconst bible-search-mode-map (make-keymap))
+(define-key bible-search-mode-map "s" 'bible-search)
+(define-key bible-search-mode-map "w" 'bible-toggle-word-study)
+(define-key bible-search-mode-map "n" 'bible-next-search-item)
+(define-key bible-search-mode-map "p" 'bible-previous-search-item)
+(define-key bible-search-mode-map (kbd "RET") 'bible-search-mode-follow-verse)
+
+(defconst bible-term-hebrew-mode-map (make-sparse-keymap))
+(defconst bible-term-greek-mode-map (make-sparse-keymap))
+
+(define-key bible-term-greek-mode-map [mouse-1] 'bible-search-mode-follow-xref)
+
 ;;;;; Navigation
 (define-key bible-map "p" 'bible-previous-chapter)
 (define-key bible-map
@@ -409,6 +428,14 @@ bible--display-lemma-hebrew."
 (define-key bible-map "\C-n" 'next-logical-line)
 (define-key bible-map "\C-p" 'previous-logical-line)
 
+;;;;; Keymap functions
+
+(defun bible-toggle-display-diatheke ()
+  "Toggle diatheke args display."
+  (interactive)
+  (setq bible-show-diatheke-exec (not bible-show-diatheke-exec))
+  (message ""))
+
 (defun bible-next-search-item ()
   "Go to next item in list of found verses."
   (interactive)
@@ -419,22 +446,13 @@ bible--display-lemma-hebrew."
   (interactive)
   (search-backward-regexp bible--verse-regexp))
 
+(defun bible-toggle-display-xml ()
+  "Toggle XML display."
+  (interactive)
+  (setq-local bible-debugme (not bible-debugme))
+  (bible--display))
 
-(defconst bible-search-mode-map (make-keymap))
-(define-key bible-search-mode-map "s" 'bible-search)
-(define-key bible-search-mode-map "w" 'bible-toggle-word-study)
-(define-key bible-search-mode-map "n" 'bible-next-search-item)
-(define-key bible-search-mode-map "p" 'bible-previous-search-item)
-(define-key bible-search-mode-map (kbd "RET") 'bible-search-mode-follow-verse)
-
-(defconst bible-term-hebrew-mode-map (make-sparse-keymap))
-(defconst bible-term-greek-mode-map (make-sparse-keymap))
-
-(define-key bible-term-greek-mode-map [mouse-1] 'bible-search-mode-follow-xref)
-
-;;;
-;;; Menu bar items
-;;;
+;;;; Menu bar items
 
 (defvar-local bible-text-direction 'left-to-right)
 
@@ -740,8 +758,8 @@ Handle abbreviations from lexicon module (AbbottSmith)."
     (bible-open (string-trim book) (string-to-number chapter) (string-to-number verse))))
 
 
-;;; These can be called interactively if you know the Strong's number
-;;; you want to look up.
+;; These can be called interactively if you know the Strong's number
+;; you want to look up.
 
 (defun bible-term-hebrew (term)
   "Query user for a Strong's Hebrew Lexicon TERM."
@@ -753,7 +771,7 @@ Handle abbreviations from lexicon module (AbbottSmith)."
   (interactive "sTerm: ")
   (bible--open-term-greek term))
 
-;;; Interactively insert a verse into an arbitrary current buffer.
+;; Interactively insert a verse into an arbitrary current buffer.
 (defun bible-insert ()
   "Query user to select a verse for insertion into the current buffer."
   (interactive)
@@ -766,13 +784,13 @@ Handle abbreviations from lexicon module (AbbottSmith)."
     (apply #'call-process args)))
 
 
-;;;;; Support
+;;;; Support
 
 (defconst bible-diatheke-filter-options " avlnmw")
 
-;;;; XXX
-;;;; Can we avoid returning (buffer-string) and just use whatever buffer is current?
-;;;;
+;; XXX
+;; Can we avoid returning (buffer-string) and just use whatever buffer is current?
+;;
 (defun bible--exec-diatheke (query &optional filter format module)
   "Execute `diatheke' with specified QUERY options, returning output
 buffer. FILTER is the Diatheke filter argument. FORMAT is either plain
@@ -811,34 +829,32 @@ module."
     (buffer-string)))
 
 
-;;; XXX Bible chapter titles mostly appear in Psalms. This code works
-;;; OK except for Psalm 119 which changes the chapter title to
-;;; indicate the Hebrew letter that each verse of a stanza begins
-;;; with.
-;;;
-;;; Chapter titles seem to be part of each verse in the modules I saw.
-;;;
-;;; Fixing this issue would require keeping track of the current
-;;; chapter title and emitting the title whenever it changed. Since
-;;; there is (AFAIK) only one chapter in the Bible that has this
+;; XXX Bible chapter titles mostly appear in Psalms. This code works
+;; OK except for Psalm 119 which changes the chapter title to indicate
+;; the Hebrew letter that each verse of a stanza begins with.
+;;
+;; Chapter titles seem to be part of each verse in the modules I saw.
+;;
+;; Fixing this issue would require keeping track of the current
+;; chapter title and emitting the title whenever it changed. Since
+;; there is (AFAIK) only one chapter in the Bible that has this
 ;;; issue, it doesn't seem like a high priority now.
 (defvar-local bible-chapter-title nil
   "Text preceding start of chapter.
 Mostly in Psalms, like `Of David' or the like.")
 
-;;;
-;;; Greek and Hebrew lexeme and morpheme tooltip rendering.
-;;;
 
-;;; Hash tables for Lexical definitions.
+;;;; Greek and Hebrew lexeme and morpheme tooltip rendering.
+
+;;;;; Hash tables for Lexical definitions.
 (defvar bible-hash-greek (make-hash-table :test 'equal :size 10000))
 (defvar bible-hash-hebrew (make-hash-table :test 'equal :size 10000))
 
-;;; Hash tables for tooltips.
+;;;;; Hash tables for tooltips.
 (defvar lex-hash (make-hash-table :test 'equal :size 10000))
 (defvar morph-hash (make-hash-table :test 'equal :size 10000))
 
-;;; Use HTMLHREF format with diatheke, post-process to render html.
+;; Use HTMLHREF format with diatheke, post-process to render html.
 (defun bible--morph-query (query module)
   "Execute `diatheke' to do morph QUERY, using MODULE.
 Render HTML, return string.  Do some tweaking specific to morphology."
@@ -855,7 +871,7 @@ Render HTML, return string.  Do some tweaking specific to morphology."
       (substring (buffer-string) (+ (length query) 1))))) ; This tries to get rid of unnecessary query identifier.
 
 
-;;; Use "plain" format with diatheke.
+;; Use "plain" format with diatheke.
 (defun bible--lex-query (query module)
   "Execute `diatheke' for QUERY, using MODULE. 
 Plain format, returns string."
@@ -870,10 +886,10 @@ Plain format, returns string."
     ""
     (bible--lex-query key bible-lexicon-index))))
 
-;;;
-;;; The Greek lexical definitions are done using the HTMLHREF output
-;;; format so they come out looking nice and having clickable
-;;; cross-references and/or Strong's references.
+;;
+;; The Greek lexical definitions are done using the HTMLHREF output
+;; format so they come out looking nice and having clickable
+;; cross-references and/or Strong's references.
 
 (defun bible--process-href ()
   "Fix the XML so cross-references are in the right format.
@@ -968,10 +984,10 @@ Massage output so various cross references are usable. Returns string."
 	       (bible--lookup-def-hebrew key)
 	       bible-hash-hebrew)))
 
-;;;
-;;; We use the shorter lexicons for text in tooltips. We also cache
-;;; the lex and morph strings, hoping to speed up tooltip rendering.
-;;;
+;;
+;; We use the shorter lexicons for text in tooltips. We also cache the
+;; lex and morph strings, hoping to speed up tooltip rendering.
+;;
 (defun bible--lookup-lemma-greek-short (lemma)
   "Look up Greek lexical entry for LEX from short Greek lexicon."
   (when (string-match "[0-9]+" lemma)
@@ -1069,9 +1085,8 @@ database and stash in cache."
     lex-text)
 
 
-;;;
-;;; Get string for tooltip display
-;;;
+
+;; Get string for tooltip display
 (defun bible--show-lex-morph (_window object pos)
   "Get text for tooltip display for OBJECT at POS in WINDOW.
 Includes both lex and morph definitions if text module has
@@ -1094,6 +1109,7 @@ both tags, otherwise just get lex definition."
 	 (string-trim lex-text))))))
 
 
+;;;; Display Bible text
 
 (defun bible-handle-divine-name (item)
   "When ITEM is divine name, display it as such."
@@ -1353,6 +1369,8 @@ supplied, set cursor at verse."
     (re-search-forward (concat " ?" (number-to-string verse)) nil t)))
 
 
+;;;; Modules (Bible texts)
+
 (defun bible--list-biblical-modules ()
   "Return a list of accessible Biblical Text modules."
   (let ((text (bible--exec-diatheke "modulelist" nil nil "system"))
@@ -1401,7 +1419,7 @@ supplied, set cursor at verse."
     (pop-to-buffer (current-buffer) nil t)))
 
 
-;;;;; Bible Searching
+;;;; Bible Searching
 
 (defun bible--open-search (query searchmode)
   "Open a search buffer of QUERY using SEARCHMODE in module MOD."
@@ -1464,8 +1482,8 @@ supplied, set cursor at verse."
     (setq mode-name (concat mode-name " [" bible-search-range "]")))
   (setq mode-name (concat mode-name ")")))
 
-;;;;; Terms (lemmas, morphemes)
 
+;;;; Terms (lemmas, morphemes)
 
 ;;(defun bible-display-morphology (morph)
 ;; ;; xxx Do something here?
@@ -1551,7 +1569,7 @@ This code is customized for the BDBGlosses_Strongs lexicon."
   (setq-local bible--current-chapter chapter)
   (bible--display verse))
 
-;;;;; Utilities
+;;;; Utilities
 
 (defun bible--list-number-range (min max &optional prefix)
   "Returns a list containing entries for each integer between MIN and MAX.
@@ -1569,7 +1587,3 @@ Used in tandem with `completing-read' for chapter selection."
 (provide 'bible)
 
 ;;; bible.el ends here.
-
-
-;; Local Variables:
-;; End: