generated

Signed-off-by: Psionik K <[email protected]>
positron-solutions · Dec 28, 2023 · d26a456 · d26a456
1 parent ff58623
commit d26a456
Show file tree

Hide file tree

Showing 3 changed files with 203 additions and 52 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,28 +5,28 @@ Development process & infrastructure guide.
 
 # Table of Contents
 
--   [Development](#org83d1291)
-    -   [Running tests](#org6fc1d97)
-    -   [Lint and byte-compile code](#orgc34e59f)
-    -   [Loading and re-loading your package](#orgf424ad0)
-    -   [Re-generating Documentation](#org08f62a4)
--   [License](#org341535c)
--   [Developer Certificate of Origin (DCO)](#org12add76)
-    -   [Sign-off](#org7f1f6d1)
-    -   [GPG signature](#orge1ebcad)
-    -   [User setup for submitting changes](#orga724bae)
-    -   [Maintaining versions](#org273f042)
+-   [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)
 
 
-<a id="org83d1291"></a>
+<a id="org2bae257"></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="org6fc1d97"></a>
+<a id="org3868b1c"></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="orgc34e59f"></a>
+<a id="org29f53c9"></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="orgf424ad0"></a>
+<a id="orgaac246f"></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="org08f62a4"></a>
+<a id="org5c6621e"></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="org341535c"></a>
+<a id="org570b2f4"></a>
 
 # License
 
 This package is distributed under the terms of the [included license](./COPYING).  The CI
 configuration and scripts are MIT licensed.
 
 
-<a id="org12add76"></a>
+<a id="org0837893"></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="org7f1f6d1"></a>
+<a id="org046d9b8"></a>
 
 ## Sign-off
 
@@ -155,7 +155,7 @@ following:
     Signed-off-by: Random J Developer <[email protected]>
 
 
-<a id="orge1ebcad"></a>
+<a id="org3c4cccc"></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="orga724bae"></a>
+<a id="org235a587"></a>
 
 ## User setup for submitting changes
 
@@ -241,7 +241,7 @@ equivalent:
     git rebase -i
 
 
-<a id="org273f042"></a>
+<a id="orgc8f3fd1"></a>
 
 ## Maintaining versions
 

diff --git a/README.md b/README.md
@@ -7,15 +7,31 @@
 
 # Scratch Packages
 
-The repository hosting this package was created with [elisp-repo-kit](https://github.com/positron-solutions/elisp-repo-kit).  You can
-clone and rename it using `erk-new` to quickly get a package set up.
+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.
 
 
-# Install Scratch Packages
+## Why You Want This
+
+Compared to using `ielm` and `lisp-interaction-mode` in regular scratch buffers,
+packages support:
+
+-   `byte-compile-and-load` to quickly reload (and let the compiler detect problems)
+-   flycheck will work better
+-   `edebug` and `debug`
+-   proper loading, unloading, reloading
+-   dependency declaration so that `use-package` etc can arrange the loading order
+-   autoloads
+
+I don't recommend `lisp-interaction` mode for scratch since packages have a lot of
+advantages, org mode is better for persistent literate exploration, and ielm
+(especially with history enabled) is better for truly ephemeral expression
+building.
+
+
+# Install
 
-    ;; update this after you publish your new package!
-    ;; (use-package scratch-pkgs) ; vanilla, assuming you have MELPA configured
-
     ;; package-vc
     (package-vc-install
      '(scratch-pkgs :url "https://github.com/positron-solutions/scratch-pkgs.git"
@@ -35,17 +51,59 @@ clone and rename it using `erk-new` to quickly get a package set up.
 
 # Table of Contents
 
--   [Contributing](#org2e31983)
+-   [Usage](#org81c61db)
+    -   [Using Your Package in Your Config](#org35bd568)
+    -   [Load Path](#orgec33624)
+-   [Contributing](#org20ae8d3)
 
 
-# Contributing
+# Usage
+
+-   Create a new package skeleton with `scratch-pkgs-new`
+-   See existing scratch packages with `scratch-pkgs`
+
+
+## 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 ⚠️)
 
-Because this repository is created from [elisp-repo-kit](https://github.com/positron-solutions/elisp-repo-kit), please file any issues
-or make relevant pull requests there unless the changes are specific to this
-repo.
+You can then declare with use-package normally:
 
-See the [CONTRIBUTING](./CONTRIBUTING.md) guide for help making changes to this project.
+    (use-package my-scratch-package)
+
+
+## Load Path
+
+You want at least **one of these** solutions in place to make sure your scratch
+packages can be used in your configuration normally.
+
+1.  Require scratch packages very early in your configuration, something like this:
+
+        (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:
+
+        (use-package my-scratch-package
+          :after scratch-pkgs)
+3.  Configure the load path manually instead:
+
+        (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-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.
+
+
+# Contributing
 
-For turn-key contribution to the software ecosystem that keeps you moving, see
-the [funding links](https://github.com/sponsors/positron-solutions).
+See the [CONTRIBUTING](./CONTRIBUTING.md) guide for help making changes to this project.  For
+turn-key contribution to the software ecosystem that keeps you moving, see the
+[funding links](https://github.com/sponsors/positron-solutions).
 
diff --git a/doc/scratch-pkgs.texi b/doc/scratch-pkgs.texi
@@ -764,28 +764,121 @@ Public License instead of this License.  But first, please read
 @end ifnottex
 
 @menu
-* Welcome::
-* Use with Elisp Repo Kit::
-* About this Manual::
+* Scratch Packages::
+* Usage::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Scratch Packages
+
+* Why You Want This::
+
+Usage
+
+* Using Your Package in Your Config::
+* Load Path::
+
+@end detailmenu
 @end menu
 
-@node Welcome
-@chapter Welcome
+@node Scratch Packages
+@chapter Scratch Packages
+
+Create quick packages for personal use in your configuration.  A more
+light-weight solution than @uref{https://github.com/positron-solutions/elisp-repo-kit, Elisp Repo Kit} for quickly developing an idea within
+a properly formed package.
+
+@menu
+* Why You Want This::
+@end menu
+
+@node Why You Want This
+@section Why You Want This
+
+Compared to using @code{ielm} and @code{lisp-interaction-mode} in regular scratch buffers,
+packages support:
+@itemize
+@item
+@code{byte-compile-and-load} to quickly reload (and let the compiler detect problems)
+@item
+flycheck will work better
+@item
+@code{edebug} and @code{debug}
+@item
+proper loading, unloading, reloading
+@item
+dependency declaration so that @code{use-package} etc can arrange the loading order
+@item
+autoloads
+@end itemize
+I don't recommend @code{lisp-interaction} mode for scratch since packages have a lot of
+advantages, org mode is better for persistent literate exploration, and ielm
+(especially with history enabled) is better for truly ephemeral expression
+building.
 
-This is a simple org document used to generate an info manual and content for
-the README@.
+@node Usage
+@chapter Usage
 
-@node Use with Elisp Repo Kit
-@chapter Use with Elisp Repo Kit
+@itemize
+@item
+Create a new package skeleton with @code{scratch-pkgs-new}
+@item
+See existing scratch packages with @code{scratch-pkgs}
+@end itemize
 
-The repository hosting this package was created with @uref{https://github.com/positron-solutions/elisp-repo-kit, elisp-repo-kit}.  You can
-clone and rename it using @code{erk-new} to quickly get a package set up.
+@menu
+* Using Your Package in Your Config::
+* Load Path::
+@end menu
 
-@node About this Manual
-@chapter About this Manual
+@node Using Your Package in Your Config
+@section Using Your Package in Your Config
 
-To see more examples of writing an org document that exports to texinfo or
-markdown, see the longer examples in Elisp Repo Kit, which is available in its
-info manual as well.
+Scratch packages works by:
+@itemize
+@item
+Creates and stores packages inside @samp{~/.emacs.d/var/scratch-pkgs/}
+@item
+Adds that path to the loading path (see options below ⚠️)
+@end itemize
+You can then declare with use-package normally:
+@lisp
+(use-package my-scratch-package)
+@end lisp
+
+@node Load Path
+@section Load Path
+
+You want at least @strong{one of these} solutions in place to make sure your scratch
+packages can be used in your configuration normally.
+@enumerate
+@item
+Require scratch packages very early in your configuration, something like this:
+@lisp
+(use-package scratch-pkgs)
+(require 'scratch-pkgs) ; this blocks, ensuring your scratch pkg will be in the load path
+@end lisp
+@item
+Add an implicit dependency in your @code{use-package} expressions:
+@lisp
+(use-package my-scratch-package
+  :after scratch-pkgs)
+@end lisp
+@item
+Configure the load path manually instead:
+@lisp
+(push load-path "~/.emacs.d/var/scratch-pkgs/")
+@end lisp
+@item
+For each package, use the explicit load path option of @code{use-package}
+(less convenient, so not recommended):
+@lisp
+(use-package my-scratch-package
+  :load-path "~/.emacs.d/var/scratch-pkgs/")
+@end lisp
+@end enumerate
+See the @ref{Lisp Libraries,Lisp Libraries,,emacs,} section of the Emacs manual and @ref{Loading,Loading,,elisp,} in the Elisp
+manual for more detailed treatment.
 
 @bye