Skip to content

Commit

Permalink
generated
Browse files Browse the repository at this point in the history
Signed-off-by: Psionik K <[email protected]>
  • Loading branch information
psionic-k committed Dec 28, 2023
1 parent ff58623 commit d26a456
Show file tree
Hide file tree
Showing 3 changed files with 203 additions and 52 deletions.
44 changes: 22 additions & 22 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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)

Expand All @@ -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

Expand All @@ -155,7 +155,7 @@ following:
Signed-off-by: Random J Developer <[email protected]>


<a id="orge1ebcad"></a>
<a id="org3c4cccc"></a>

## GPG signature

Expand All @@ -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

Expand Down Expand Up @@ -241,7 +241,7 @@ equivalent:
git rebase -i


<a id="org273f042"></a>
<a id="orgc8f3fd1"></a>

## Maintaining versions

Expand Down
86 changes: 72 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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).

125 changes: 109 additions & 16 deletions doc/scratch-pkgs.texi
Original file line number Diff line number Diff line change
Expand Up @@ -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

0 comments on commit d26a456

Please sign in to comment.