generated

Signed-off-by: Psionik K <[email protected]>
positron-solutions · Jan 19, 2024 · 97cd179 · 97cd179
1 parent 891d267
commit 97cd179
Show file tree

Hide file tree

Showing 3 changed files with 229 additions and 65 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,28 +5,28 @@ Development process & infrastructure guide.
 
 # Table of Contents
 
--   [Development](#org2bae257)
-    -   [Running tests](#org3868b1c)
-    -   [Lint and byte-compile code](#org29f53c9)
-    -   [Loading and re-loading your package](#orgaac246f)
-    -   [Re-generating Documentation](#org5c6621e)
--   [License](#org570b2f4)
--   [Developer Certificate of Origin (DCO)](#org0837893)
-    -   [Sign-off](#org046d9b8)
-    -   [GPG signature](#org3c4cccc)
-    -   [User setup for submitting changes](#org235a587)
-    -   [Maintaining versions](#orgc8f3fd1)
+-   [Development](#org5bbc3af)
+    -   [Running tests](#org1a12611)
+    -   [Lint and byte-compile code](#org7b6b563)
+    -   [Loading and re-loading your package](#org25fd8cf)
+    -   [Re-generating Documentation](#org8e3eded)
+-   [License](#orga24af47)
+-   [Developer Certificate of Origin (DCO)](#org984d390)
+    -   [Sign-off](#org95dfcb4)
+    -   [GPG signature](#org764ae01)
+    -   [User setup for submitting changes](#orgc7fe8d2)
+    -   [Maintaining versions](#org0ce6520)
 
 
-<a id="org2bae257"></a>
+<a id="org5bbc3af"></a>
 
 # Development
 
 This repository was created with [elisp-repo-kit](https://github.com/positron-solutions/elisp-repo-kit/).  You can use it to streamline
 development workflows.
 
 
-<a id="org3868b1c"></a>
+<a id="org1a12611"></a>
 
 ## Running tests
 
@@ -54,7 +54,7 @@ have.  **You do not need Nix to run tests pretty close to what CI does.** CI
 will use Nix to obtain Emacs & dependencies.
 
 
-<a id="org29f53c9"></a>
+<a id="org7b6b563"></a>
 
 ## Lint and byte-compile code
 
@@ -78,7 +78,7 @@ You can run the lints manually almost the same as running tests.
     emacs --script .github/run-shim.el -- lint-tests
 
 
-<a id="orgaac246f"></a>
+<a id="org25fd8cf"></a>
 
 ## Loading and re-loading your package
 
@@ -101,7 +101,7 @@ directly, call `emacs-lisp-byte-compile-and-load` or
 `emacs-lisp-native-compile-and-load`.
 
 
-<a id="org5c6621e"></a>
+<a id="org8e3eded"></a>
 
 ## Re-generating Documentation
 
@@ -123,15 +123,15 @@ manually type the path to the `manual.info`.  Honestly, just use
  because they use `#+include:` directives.
 
 
-<a id="org570b2f4"></a>
+<a id="orga24af47"></a>
 
 # License
 
 This package is distributed under the terms of the [included license](./COPYING).  The CI
 configuration and scripts are MIT licensed.
 
 
-<a id="org0837893"></a>
+<a id="org984d390"></a>
 
 # Developer Certificate of Origin (DCO)
 
@@ -144,7 +144,7 @@ A [copy of the DCO](./DCO) is distributed with this project.  Read its text to
 understand the significance of configuring for sign-off.
 
 
-<a id="org046d9b8"></a>
+<a id="org95dfcb4"></a>
 
 ## Sign-off
 
@@ -155,7 +155,7 @@ following:
     Signed-off-by: Random J Developer <[email protected]>
 
 
-<a id="org3c4cccc"></a>
+<a id="org764ae01"></a>
 
 ## GPG signature
 
@@ -166,7 +166,7 @@ participating in.  Corroborating user's signature accross a history of works
 strengthens that user's attestation provided by DCO sign-off.
 
 
-<a id="org235a587"></a>
+<a id="orgc7fe8d2"></a>
 
 ## User setup for submitting changes
 
@@ -241,7 +241,7 @@ equivalent:
     git rebase -i
 
 
-<a id="orgc8f3fd1"></a>
+<a id="org0ce6520"></a>
 
 ## Maintaining versions
 

diff --git a/README.md b/README.md
@@ -11,6 +11,9 @@ Create quick packages for personal use in your configuration.  A more
 light-weight solution than [Elisp Repo Kit](https://github.com/positron-solutions/elisp-repo-kit) for quickly developing an idea within
 a properly formed package.
 
+⚠️ **This package will likely be rolled into Elisp Repo Kit** ⚠️
+⚠️ \*The functionality is pre-release.  File bugs. ⚠️
+
 
 ## Why You Want This
 
@@ -29,6 +32,8 @@ advantages, org mode is better for persistent literate exploration, and ielm
 (especially with history enabled) is better for truly ephemeral expression
 building.
 
+In addition, many packages for Editing Elisp such as Lispy contains shortcuts for evaluating expressions before the point or evaluating them in the context of the other window.  This last advantage really undermines the functionality provided in `lisp-interaction-mode`
+
 
 # Install
 
@@ -51,10 +56,10 @@ building.
 
 # Table of Contents
 
--   [Usage](#org81c61db)
-    -   [Using Your Package in Your Config](#org35bd568)
-    -   [Load Path](#orgec33624)
--   [Contributing](#org20ae8d3)
+-   [Usage](#org6d2b36b)
+    -   [Customization](#org7ef8536)
+    -   [Using Your Package in Your Config](#org9c4b3fc)
+-   [Contributing](#org64380e8)
 
 
 # Usage
@@ -63,42 +68,100 @@ building.
 -   See existing scratch packages with `scratch-pkgs`
 
 
+## Customization
+
+-   `scratch-pkgs-mode` controls the manner of integration with your Elisp package management strategy.  See the next section on using your package in your config.
+-   `scratch-pkgs-template` customize initial buffer contents ⚠️ unstable ⚠️
+-   `scratch-pkgs-init` function passed each new buffer.  Use to perform full customization of your new buffer behavior.
+-   `scratch-pkgs-after-new-hook` runs after creating a buffer.  `scratch-pkgs-init` can do the same things, but this hook requires less care.
+-   `scratch-pkgs-after-package-init-hook` runs only when you save your scratch buffer.  Because integrating the package with your Elisp package management may require setting up a git repository, much work is done only after the first save of a brand new package.  This hook runs after initialization.  You could run `magit-status` for instance to remind yourself of what was created after the first save.
+
+
 ## Using Your Package in Your Config
 
 Scratch packages works by:
 
--   Creates and stores packages inside `~/.emacs.d/var/scratch-pkgs/`
--   Adds that path to the loading path (see options below ⚠️)
-
-You can then declare with use-package normally:
+-   Creates and stores packages inside `~/.emacs.d/etc/scratch-pkgs/`
+-   Integrates with your usual package loading (see options below ⚠️)  You can then declare with use-package normally:
 
     (use-package my-scratch-package)
 
 
-## Load Path
+### Correct Loading & Initialization Order
+
+Scratch packages can integrate with Elisp package managers to streamline using your packages in your configuration.  It must to be loaded and perform initialization *before* your personal packages are loaded.
 
-You want at least **one of these** solutions in place to make sure your scratch
-packages can be used in your configuration normally.
+-   Load Path Initialization
 
-1.  Require scratch packages very early in your configuration, something like this:
+    **Keep in mind, setting the load path will not handle your custom package dependencies**   One of the following solutions will make your packages available for simple `(require 'my-package)` expressions.
+
+    1.  Require scratch packages very early in your configuration, something like this:
+
+            (use-package scratch-pkgs)
+            (require 'scratch-pkgs)
+            (setopt scratch-pkgs-mode 'local)
+            (scratch-pkgs-integrate)
+
+    2.  Configure the load path manually instead:
+
+            (push load-path "~/.emacs.d/var/scratch-pkgs/")
+    3.  For each package, use the explicit load path option of `use-package`
+        (less convenient, so not recommended):
+
+            (use-package my-scratch-package
+              :load-path "~/.emacs.d/var/scratch-pkgs/")
+
+    See the [Lisp Libraries](emacs#Lisp Libraries) section of the Emacs manual and [Loading](elisp#Loading) in the Elisp
+    manual for more detailed treatment.
+
+-   Elpaca Initialization
+
+    Usually just after loading other load-order sensitive packages like `no-littering`, you can load `scratch-pkgs` and perform integration:
+
+        (elpaca (scratch-pkgs
+                 :host github :repo "positron-solutions/scratch-pkgs")
+          (require 'scratch-pkgs)
+          (setopt scratch-pkgs-mode 'elpaca)
+          (scratch-pkgs-integrate))
 
-        (use-package scratch-pkgs)
-        (require 'scratch-pkgs) ; this blocks, ensuring your scratch pkg will be in the load path
-2.  Add an implicit dependency in your `use-package` expressions:
+    Afterwards, `(use-package my-package)` will just work **and** Elpaca will handle the dependencies.
+
+-   Straight
+
+    **TODO**.  Other Elisp package management integrations to streamline usage are welcome.
+
+-   Package
+
+    **TODO**.  Likely we should use some `package-vc-install` style solution.
+
+
+### Package Management Integration
+
+-   Load Path
+
+    If you followed the initialization instructions above, your package is already on the load path.  However, manual load-path packages don't do any automated dependency handling.  You can declare this manually:
 
-        (use-package my-scratch-package
-          :after scratch-pkgs)
-3.  Configure the load path manually instead:
+        (use-package my-package
+          :requires foo)
+
+        (use-package my-package
+          :requires (foo bar baz))
+
+-   Elpaca
+
+    Having Elpaca fetch dependencies and build your package is easy:
 
-        (push load-path "~/.emacs.d/var/scratch-pkgs/")
-4.  For each package, use the explicit load path option of `use-package`
-    (less convenient, so not recommended):
+        (use-package my-package)
 
-        (use-package my-scratch-package
-          :load-path "~/.emacs.d/var/scratch-pkgs/")
+    ⚠️ Updates are **not** automatic in this workflow.  You need to commit changes you want to install permanently and then run `elpaca-fetch` and `elpaca-merge` to install your modifications into the `repos/` of your `elpaca-directory`
+
+-   Straight
+
+    **TODO**.  Other Elisp package management integrations to streamline usage are welcome.
+
+-   Package
 
-See the [Lisp Libraries](emacs#Lisp Libraries) section of the Emacs manual and [Loading](elisp#Loading) in the Elisp
-manual for more detailed treatment.
+    **TODO**.  Likely we should use some `package-vc-install` style solution.
 
 
 # Contributing