Add README.md

Document how to add the overlay, list the packages it carries, and
note that virtual/mta needs a package.mask entry to actually override
the main tree on a --getbinpkg setup.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..b47fc28
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# shuber Gentoo overlay
+
+Stefan Huber's personal Gentoo ebuild overlay. Mostly packages that
+aren't (or are no longer) in the main Gentoo tree, plus a few local
+overrides of main-tree packages. A handful of the packages
+(`app-backup/sitarba`, `games-util/joydevmap`, `mail-mta/smailq`) are
+ebuilds for Stefan's own software.
+
+## Adding this overlay
+
+```
+# /etc/portage/repos.conf/shuber.conf
+[shuber]
+location = /usr/local/portage/shuber/
+sync-type = git
+sync-uri = git.sthu.org:~/gitweb/shuber-gentoo-overlay.git
+priority = 50
+```
+
+`metadata/layout.conf` sets `masters = gentoo`, so this overlay expects
+the main Gentoo tree to also be available.
+
+To make the `virtual/mta` override actually take effect (see
+[Notes](#notes) below), also mask the main tree's copy:
+
+```bash
+echo 'virtual/mta::gentoo' | sudo tee /etc/portage/package.mask/virtual-mta-shuber
+```
+
+## Packages
+
+| Package | Description |
+| --- | --- |
+| app-backup/sitarba | A simple tar-based backup tool |
+| app-text/shrinkpdf | Shrink PDF files with Ghostscript |
+| dev-debug/gdb-dashboard | Modular visual interface for GDB in Python |
+| dev-embedded/simavr | Atmel AVR simulator |
+| dev-embedded/simulavr | A simulator for the Atmel AVR family of microcontrollers |
+| dev-libs/core | Exact arithmetics library intended for exact geometric computations |
+| dev-tex/git-latexdiff | A wrapper around git and latexdiff |
+| games-util/joydevmap | A simple tool to set axis and button maps of joysticks |
+| gui-apps/wayland-pipewire-idle-inhibit | Inhibit Wayland idle when audio is playing through PipeWire |
+| mail-mta/smailq | A simple mail queue |
+| media-gfx/cgal-ipelets | Ipe addons shipped with the CGAL library |
+| media-gfx/ipe | Drawing editor for creating figures in PDF or PS formats |
+| media-gfx/ipe-tools | Tools to use with the Ipe drawing editor |
+| media-libs/libspiro | A library for drawing beautiful curves |
+| virtual/mta | Virtual for Message Transfer Agents (local override, see below) |
+| x11-apps/inputplug | XInput event monitor daemon |
+
+## Notes
+
+- `virtual/mta` is a local override that adds `mail-mta/smailq[mta]` as
+  a provider. Version-matching the main tree's revision plus this
+  overlay's `priority` is **not** enough to make it win on a
+  `--getbinpkg` setup: an identically-versioned binary from the main
+  tree's binhost will still outrank building this ebuild. Add
+  `virtual/mta::gentoo` to `/etc/portage/package.mask` to force this
+  override to actually take effect.
+
+## Licensing
+
+Ebuilds are distributed under the GNU General Public License v2, per
+the standard Gentoo ebuild header, unless noted otherwise in the file.