Merge pull request #148 from kickingvegas/merge-development-to-main-2…

…0240605_172435

Merge development to main 20240605_172435

Makefile

@@ -44,7 +44,7 @@
 
 CASUAL_LISP_DIR=./lisp
 CASUAL_EL=$(CASUAL_LISP_DIR)/casual.el
-CASUAL_VERSION_EL=$(CASUAL_LISP_DIR)/casual-version.el
+CASUAL_VERSION_EL=$(CASUAL_LISP_DIR)/casual-calc-version.el
 
 TIMESTAMP := $(shell /bin/date "+%Y%m%d_%H%M%S")
 CASUAL_VERSION := $(shell ./scripts/read-version.sh $(CASUAL_EL))
@@ -74,7 +74,7 @@ tests:
 ## Bump Patch Version
 bump-casual:
 	sed -i 's/;; Version: $(CASUAL_VERSION)/;; Version: $(CASUAL_VERSION_BUMP)/' $(CASUAL_EL)
-	sed -i 's/(defconst casual-version "$(CASUAL_VERSION)"/(defconst casual-version "$(CASUAL_VERSION_BUMP)"/' $(CASUAL_VERSION_EL)
+	sed -i 's/(defconst casual-calc-version "$(CASUAL_VERSION)"/(defconst casual-calc-version "$(CASUAL_VERSION_BUMP)"/' $(CASUAL_VERSION_EL)
 
 bump: checkout-development bump-casual
 	git commit -m 'Bump version to $(CASUAL_VERSION_BUMP)' $(CASUAL_EL) $(CASUAL_VERSION_EL)

README.org

@@ -1,5 +1,5 @@
 [[https://melpa.org/#/casual][file:https://melpa.org/packages/casual-badge.svg]]
-* Casual
+* Casual Calc
 An opinionated [[https://github.com/magit/transient][Transient]]-based porcelain to support the casual usage of Emacs [[https://www.gnu.org/software/emacs/manual/html_mono/calc.html][Calc]].
 
 [[file:docs/images/casual-main-menu.png]]
@@ -11,7 +11,7 @@ Menus are a user interface (UI) affordance that offer users discoverability and
 
 ** Goals
 - To provide a keyboard-driven UI to Calc that is menu based.
-- To allow users experienced with scientific calculators to casually use Calc without resorting to its Info pages.
+- To allow users experienced with scientific calculators to casually use Calc without requiring reference to its Info manual.
 
 ** Non-Goals
 - Full coverage of all Calc commands. Casual is not intended to be a power user tool.
@@ -27,21 +27,15 @@ Casual is available on [[https://melpa.org/#/casual][MELPA]].
 
 If installed via ~list-packages~ then add this line to your Emacs initialization file.
 #+begin_src elisp :lexical no
-  (define-key calc-mode-map (kbd "C-o") 'casual-main-menu)
+  (require 'casual) ;; optional
+  (define-key calc-mode-map (kbd "C-o") #'casual-calc-tmenu)
 #+end_src
 
 If you use ~use-package~, here is the recipe for installing it.
 #+begin_src elisp :lexical no
   (use-package casual
     :ensure t
-    :bind (:map calc-mode-map ("C-o" . 'casual-main-menu)))
-#+end_src
-
-If you are installing by using a clone of this repository, then ensure that the directory holding ~casual.el~ is in your ~info-path~. Add the following lines to your Emacs initialization file.
-
-#+begin_src elisp :lexical no
-  (require 'casual)
-  (define-key calc-mode-map (kbd "C-o") 'casual-main-menu)
+    :bind (:map calc-mode-map ("C-o" . #'casual-calc-tmenu)))
 #+end_src
 
 Casual requires Emacs 29.1+.
@@ -51,7 +45,7 @@ Casual requires Emacs 29.1+.
 2. When the point is in the Calc window, invoke ~C-o~ (or a binding of your choosing) to launch the Casual menu.
 
 * Common Menu Actions
-Casual is built using Transient menus and as such adopts much of its default behavior.
+Casual Calc is built using Transient menus and as such adopts much of its default behavior.
 
 Each menu item has a /key/ and a /label/. The /key/ is what is typed by the user to select the menu item. A key can be prefixed with a meta (M-) or control (C-) key. Labels ending with a ~>~ character indicates that it will open another menu.
 
@@ -96,12 +90,20 @@ It helps to know some basics about Calc.
 - Entering a single quote (') will prompt you for an algebraic entry.
 
 * Development
-For users who wish to help contribute to Casual or personally customize it for their own usage, please read the [[docs/developer.org][developer documentation]].
+For users who wish to help contribute to Casual Calc or personally customize it for their own usage, please read the [[docs/developer.org][developer documentation]].
 
 * Sponsorship
 If you enjoy using Casual, consider making a modest financial contribution to help support its development and maintenance.
 
 [[https://www.buymeacoffee.com/kickingvegas][file:docs/images/default-yellow.png]]
 
+* See Also
+If you like Casual Calc, these other Emacs packages might interest you:
+
+- [[https://github.com/kickingvegas/casual-dired][Casual Dired]] - an opinionated Transient porcelain for the file manager Dired.
+- [[https://github.com/kickingvegas/casual-info][Casual Info]] - an opinionated Transient porcelain for the Info reader.
+- [[https://github.com/kickingvegas/casual-avy][Casual Avy]] - an opinionated Transient porcelain for Avy, a package for jumping to visible text using a char-based decision tree.
+- [[https://github.com/kickingvegas/cc-isearch-menu][cc-isearch-menu]] - A Transient menu for I-Search.
+
 * Acknowledgments
 A heartfelt thanks to all the contributors to Calc and Transit. Casual would not be possible without your efforts.

docs/developer.org

@@ -1,10 +1,10 @@
-* Casual Development
-Casual is an open source project and as such is always open for contributors to its development.
+* Casual Calc Development
+Casual Calc is an open source project and as such is always open for contributors to its development.
 
 This document provides guidance on how to contribute to its development from a programming perspective.
 
 * Development Environment
-Casual is developed primarily using a GNU toolchain. GNU tools required are:
+Casual Calc is developed primarily using a GNU toolchain. GNU tools required are:
 
 - make
 - awk
@@ -13,30 +13,30 @@ Casual is developed primarily using a GNU toolchain. GNU tools required are:
 
 Also needed is the Python [[https://pypi.org/project/semver/][semver]] module. This will require an installation of Python 3.x, ideally at 3.9 or higher.
 
-For source code management, Casual uses ~git~.
+For source code management, Casual Calc uses ~git~.
 
 Given a clone of this repository, ensure that the directory holding ~casual.el~ is in your ~info-path~. Add the following lines to your Emacs initialization file.
 #+begin_src elisp :lexical no
   (require 'casual)
-  (define-key calc-mode-map (kbd "C-o") 'casual-main-menu)
+  (define-key calc-mode-map (kbd "C-o") #'casual-calc-tmenu)
 #+end_src
 
 * Branches
-For Casual development, there are two git branches of note:
+For Casual Calc development, there are two git branches of note:
 
 - [[https://github.com/kickingvegas/Casual/tree/main][main]] for releases to the general public.
 - [[https://github.com/kickingvegas/Casual/tree/development][development]] for staging of stable pre-release functionality.
 
 Planned changes for the next release are done on feature branches that are merged via pull request into ~development~. Upon QA of ~development~, those changes are merged to ~main~ for release to the general public.
 
 * Test Regression
-Running the Casual test regression suite is done via Makefile. In the top-level directory of Casual, run this from the command line.
+Running the Casual Calc test regression suite is done via Makefile. In the top-level directory of Casual Calc, run this from the command line.
 
 #+begin_src text
   $ make tests
 #+end_src
 
-Casual uses the [[https://www.gnu.org/software/emacs/manual/html_node/ert/][ERT]] framework to compose and manage tests.
+Casual Calc uses the [[https://www.gnu.org/software/emacs/manual/html_node/ert/][ERT]] framework to compose and manage tests.
 
 One can run a test for a single file by using a "phony" target with a suffix of ~.elt~ in the ~lisp/~ directory containing all the source files.
 
@@ -62,16 +62,16 @@ Before you submit a pull request (PR):
   - If the pull request is made against ~main~ but can be re-targeted to ~development~, it will be reviewed.
   - A pull request with merge conflicts to ~development~ will be summarily rejected.
 
-All of the above is intended to ensure that Casual releases are of high quality.
+All of the above is intended to ensure that Casual Calc releases are of high quality.
 
 * UX Guidelines
 
 - Menus must not exceed 80 characters in length.
-  - Rationale: Casual follows suit with current Elisp format to conform to the line width of an ADM-3A terminal.
-- Casual UX does not use the Calc /inverse/ or /hyperbolic/ key modifier.
+  - Rationale: Casual Calc follows suit with current Elisp format to conform to the line width of an ADM-3A terminal.
+- Casual Calc UX does not use the Calc /inverse/ or /hyperbolic/ key modifier.
   - Calc functions requiring such modifiers are "flattened" into workflows that obviate them.
     - Example: implement the menu item /arcsin/ instead of /inverse sin/.
-  - Rationale: Calc's support for /inverse/ and /hyperbolic/ keys is itself an emulation of Hewlett-Packard (HP) calculator behavior which was designed to compensate for its finite number of hardware buttons. As Casual is a software menu porcelain, there are no such UX restrictions so it makes no effort to emulate hardware key modifiers. Furthermore, the semantics of /inverse/ and /hyperbolic/ only apply to some functions, but Calc has overused them to support functions where it semantically makes no sense (e.g. ~inverse calc-fin-fv~ to get the future value at the beginning of a payment interval). Casual takes the opportunity to cease this practice.
+  - Rationale: Calc's support for /inverse/ and /hyperbolic/ keys is itself an emulation of Hewlett-Packard (HP) calculator behavior which was designed to compensate for its finite number of hardware buttons. As Casual Calc is a software menu porcelain, there are no such UX restrictions so it makes no effort to emulate hardware key modifiers. Furthermore, the semantics of /inverse/ and /hyperbolic/ only apply to some functions, but Calc has overused them to support functions where it semantically makes no sense (e.g. ~inverse calc-fin-fv~ to get the future value at the beginning of a payment interval). Casual Calc takes the opportunity to cease this practice.
 - Calc commands must be wrapped to include:
   - A docstring describing its behavior and a reference section linking to:
     - a Calc Info page describing the behavior of the wrapped function.

lisp/Makefile

@@ -26,37 +26,37 @@ else
 endif
 
 CASUAL_INCLUDES =				\
-casual-calc.el					\
+casual-calc--calc.el				\
 casual-calc-algebra.el				\
-casual-predicates.el				\
-casual-labels.el				\
-casual-fileio.el 				\
-casual-radix.el					\
-casual-angle-measure.el				\
-casual-stack.el					\
-casual-variables.el				\
-casual-graphics.el				\
-casual-version.el
+casual-calc-predicates.el			\
+casual-calc-labels.el				\
+casual-calc-fileio.el				\
+casual-calc-radix.el				\
+casual-calc-angle-measure.el			\
+casual-calc-stack.el				\
+casual-calc-variables.el			\
+casual-calc-graphics.el				\
+casual-calc-version.el
 
 CASUAL_PACKAGES=				\
-casual-binary.el				\
-casual-complex.el				\
-casual-conversion.el				\
-casual-logarithmic.el				\
-casual-random.el				\
-casual-rounding.el				\
-casual-rounding.el				\
-casual-settings.el				\
-casual-time.el					\
-casual-trail.el					\
-casual-trigonometric.el				\
-casual-units.el					\
-casual-vector.el				\
-casual-financial.el				\
-casual-symbolic.el
+casual-calc-binary.el				\
+casual-calc-complex.el				\
+casual-calc-conversion.el			\
+casual-calc-logarithmic.el			\
+casual-calc-random.el				\
+casual-calc-rounding.el				\
+casual-calc-rounding.el				\
+casual-calc-settings.el				\
+casual-calc-time.el				\
+casual-calc-trail.el				\
+casual-calc-trigonometric.el			\
+casual-calc-units.el				\
+casual-calc-vector.el				\
+casual-calc-financial.el			\
+casual-calc-symbolic.el
 
 CASUAL_TEST_INCLUDES= \
-casual-test-utils.el
+casual-calc-test-utils.el
 
 .PHONY: tests compile regression
 
@@ -87,7 +87,7 @@ casual.elt: casual.el
 $(patsubst %, -l %, $(CASUAL_INCLUDES)) \
 $(patsubst %, -l %, $(CASUAL_PACKAGES)) \
 -l $< \
--l ../tests/casual-test-utils.el \
+-l ../tests/casual-calc-test-utils.el \
 -l $(patsubst %, ../tests/test-%, $<) \
 -f ert-run-tests-batch-and-exit