Generated readme and texinfo manual

The documentation was moved to /doc and broken up so that there is now a manual
and the README includes sections of the manual.  The contributing guide was
mostly left as-is.

Table of contents no longer relies on org-toc

Several helper commands to export and view the correct files were created.

ERK now reads its own attributes to decide how to perform author renaming and
also uses these during document generation

The documentation generation was documented.  Oh god.

Lots of little documentation tweaks were done to format or support the exports.

generated documentation found in new README.md, CONTRIBUTING.md, and manual.texi

Signed-off-by: Psionik K <[email protected]>

.github/workflows/ci.yml

@@ -43,6 +43,8 @@ jobs:
         os: [ubuntu-latest, macos-latest]
         emacsPkg: [ emacs, emacsGit, ]
     runs-on: ${{ matrix.os }}
+    # If you update steps, be sure to update the approved actions list in the
+    # manual and in your repositories!
     steps:
       - uses: actions/[email protected]
         with:

.gitignore

@@ -3,4 +3,5 @@
 ***autoloads.el
 **trash
 **~
-**.~undo-tree
+**.~undo-tree
+/docs/manual.info

CONTRIBUTING.md

@@ -0,0 +1,238 @@
+[comment]: !!!THIS FILE HAS BEEN GENERATED!!! Edit README.org
+
+Development process & infrastructure guide.
+
+
+# Table of Contents
+
+-   [Development](#org3ea5530)
+    -   [Running tests](#org8b93397)
+    -   [Lint and byte-compile code](#orgaf9de15)
+    -   [Loading and re-loading your package](#orgfa05693)
+-   [License](#org94a766b)
+-   [Developer Certificate of Origin (DCO)](#orga76d644)
+    -   [Sign-off](#orga4c7da0)
+    -   [GPG signature](#org360d290)
+    -   [User setup for submitting changes](#org50831e6)
+    -   [Maintaining versions](#org3c71a76)
+
+
+<a id="org3ea5530"></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="org8b93397"></a>
+
+## Running tests
+
+Run `erk-ert-project` within this project.  The tests will be
+discovered, rebuilt & reloaded if necessary, and run.  There are a
+few other commands to augment the [ert](https://www.gnu.org/software/emacs/manual/html_node/ert/) package.
+
+
+### Running tests CI style
+
+If you cannot reproduce a failure (or success) on CI, then you may
+want to switch to using [nix](https://nixos.org/download.html) to get a reprodicible toolchain so you
+can further develop with frozen versions from the nix [flake's](https://nixos.wiki/wiki/Flakes)
+flake.lock.
+
+
+    nix develop .github# # loads the devShells.default from flake.nix
+    cd .github && direnv allow # same as above with file watching
+
+    emacs --quick --load .github/run-shim.el -- test # graphical
+    emacs --script .github/run-test.el -- test # terminal, batch style
+
+You can *totally* run the tests locally on whatever version of Emacs you
+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="orgaf9de15"></a>
+
+## Lint and byte-compile code
+
+This package uses [elisp-lint](https://github.com/gonewest818/elisp-lint) to detect issues with byte compiling, package
+format, code structure and others.
+
+The configuration is found inside [.github/run-shim.el](../.github/run-shim.el).  The CI run is invoked
+inside of [ci.yml](../.github/workflows/ci.yml) using Emacs in script mode.  Most of the configuration is in
+the run shim.
+
+The tests are also linted, to a less restrictive standard, also found in
+[run-shim.el](../.github/run-shim.el)
+
+You can run the lints manually almost the same as running tests.
+
+
+    nix develop .github#
+    # nix develop .#emacs28
+    # nix develop .#emacsGit
+    emacs --script .github/run-shim.el -- lint
+    emacs --script .github/run-shim.el -- lint-tests
+
+
+<a id="orgfa05693"></a>
+
+## Loading and re-loading your package
+
+Run `erk-reload-package` in one of your project files.  All features
+in the /lisp directory will be re-compiled and loaded appropriately.
+
+**Note**, during reloading, unloading the current module is forced.  If other
+packages you use depend on the project feature, results may be unpredicatable.
+This is one reason batch style testing can be preferred.
+
+
+### Manual Loading & Reloading
+
+To manually unload, run built-in command `unload-feature` and select your
+package name. If you do not unload, reloading has no effect and you will see
+stale behavior.
+
+Next, add the package to your load-path and then require it or, more
+directly, call `emacs-lisp-byte-compile-and-load` or
+`emacs-lisp-native-compile-and-load`.
+
+
+<a id="org94a766b"></a>
+
+# License
+
+This package is distributed under the terms of the [included license](./COPYING).  The CI
+configuration and scripts are MIT licensed.
+
+
+<a id="orga76d644"></a>
+
+# Developer Certificate of Origin (DCO)
+
+This project is distributed with a Developer Certificate of Origin.  By adding
+a sign-off notice and GPG signature to each commit, you will provide means to
+authenticate your sign-off later strengthening your attestations stated in the
+DCO, upholding the overall integrity of the license coverage over the project.
+
+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="orga4c7da0"></a>
+
+## Sign-off
+
+A sign-off means adding a "trailer" to your commit that looks like the
+following:
+
+
+    Signed-off-by: Random J Developer <[email protected]>
+
+
+<a id="org360d290"></a>
+
+## GPG signature
+
+A GPG signed commit shows that the owner of the private key submitted the
+changes.  Wherever signatures are recorded in chains, they can demonstrate
+participation in changes elsewhere and awareness of what the submitter is
+participating in.  Corroborating user's signature accross a history of works
+strengthens that user's attestation provided by DCO sign-off.
+
+
+<a id="org50831e6"></a>
+
+## User setup for submitting changes
+
+Follow these instructions before you get ready to submit a pull-request.
+
+Refer to the [GitHub signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) instructions to set up your git client
+to add GPG signatures.  File issues if you run into Emacs-specific problems.
+Be sure to use a Github verified email.
+
+Because signing is intended to be a conscious process, please remember to
+read and understand the [Developer Certificate of Origin](../DCO) before confinguring
+your client to automatically sign-off on commits.
+
+
+### Automatically add sign-off
+
+In magit, set the `-s` switch.  Use `C-x C-s` (`transient-save`) to
+preserve this switch on future uses.  (Note, this is not per-project).You
+can also set the signature flag this way.
+
+
+### Automatic GPG signing with per-project keys
+
+In order to specify which projects you intend to sign with which keys, you
+will want to configure your git client using path-specific configurations.
+
+Configuing git for this can be done with the following directory structure:
+
+
+    /home/rjdeveloper/
+    ├── .gitconfig
+    └── .gitconfig.d
+        ├── sco-linux-projects.conf
+        ├── other-projects.conf
+        └── gpg-signing-projects.conf
+
+In your root config, `.gitconfig`, add an `includeIf` directive that will
+load the configuration you use for projects you intend to GPG sign commits
+for.
+
+
+    [includeIf "gitdir:/home/rjdeveloper/**/gpg-signing/**/.git"]
+      path = "~/.gitconfig.d/gpg-signing-projects.conf"
+
+In the `gpg-signing-projects.conf` add your GPG signing configuration from
+earlier.  `sign` adds the GPG signature automatically.  File an issue if you
+need help with multiple GPG homes or other configurations.
+
+
+    [user]
+      name = "Random J Developer"
+      email = "[email protected]"
+      signingkey = "5FF0EBDC623B3AD4"
+
+    [commit]
+      sign = true
+      gpgSign = true
+
+
+### Manually signing & adding sign-off
+
+If you don't like these configurations and want to individually indicate you
+have read and intend to apply the DCO to your changes, these commands are
+equivalent:
+
+    git commit -s -S --message "I don't like using .gitconfig"
+
+    # To clean up a commit
+    git commit --amend -s -S --no-message
+
+    # Combine with rebase to sign / sign-off multiple existing commits
+    git rebase -i
+
+
+<a id="org3c71a76"></a>
+
+## Maintaining versions
+
+The Nix [flake.nix](../github/flake.nix) is where versions are declared.  The [flake.lock](../.github/flake.lock) stores a
+fixed value for these declarations.  These fixed versions need periodic
+update.  Nixpkgs has a new release about every six months.  You can check
+their [branches](https://github.com/NixOS/nixpkgs/branches) and [tags](https://github.com/NixOS/nixpkgs/tags) to see what's current.  The effect is similar to
+updating linux versions.  The `nix` command has a lot of support for
+specifying versions besides just updating.
+
+    nix flake lock --update-input nixpkgs
+
+The `emacs-overlay`, which contains fixed versions of Emacs and snapshots of
+Elisp repository package sets can be updated by running:
+
+    nix flake lock --update-input emacs-overlay
+