From 09c5fc02e2b5d39fe8009cd78e7c50b7c293efa8 Mon Sep 17 00:00:00 2001
From: George Rawlinson <george@rawlinson.net.nz>
Date: Sat, 24 Jul 2021 14:51:34 +0000
Subject: [PATCH] docs: consolidate readme files

---
 .repo/README.md | 23 --------------
 README.md       | 82 +++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 65 insertions(+), 40 deletions(-)
 delete mode 100644 .repo/README.md

diff --git a/.repo/README.md b/.repo/README.md
deleted file mode 100644
index 206231c..0000000
--- a/.repo/README.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# README
-
-Ensure local repository is in `/etc/pacman.conf`, using the `file://` format.
-
-```conf
-[grawlinson]
-Server = file:///var/lib/repo/grawlinson
-```
-
-Ensure GPG keys for signing packages & repositories have been created,
-and exist in pacman's keyring.
-
-Copy aurutils configuration to the global directory.
-
-```sh
-cp -t /etc/aurutils {pacman,makepkg}-grawlinson.conf
-```
-
-Create a `systemd-nspawn` instance for aurbuild.
-
-```sh
-aur chroot --create -M /etc/aurutils/makepkg-grawlinson.conf -C /etc/aurutils/pacman-grawlinson.conf
-```
diff --git a/README.md b/README.md
index 2989b80..2713b4a 100644
--- a/README.md
+++ b/README.md
@@ -2,34 +2,82 @@
 
 Code for `grawlinson` repository.
 
-## Scripts
+## Setup
 
+**Note**: Creation of a brand spankin' new repository is not documented here.
+
+* Ensure local repository is in `/etc/pacman.conf`, using the `file://` format.
+
+```conf
+[grawlinson]
+Server = file:///var/lib/repo/grawlinson
 ```
- build   build specified package(s) and add to local repo [default:all]
- check   use nvchecker to check for new package versions
- clean   remove old packages from local repo
- remove  remove specified package(s) from local repo
- sync    sync local repo with remote repo
+
+* Ensure GPG keys for signing packages & repositories have been created,
+ and exist in pacman's keyring.
+
+* Copy aurutils configuration to the global directory.
+
+```sh
+cp -t /etc/aurutils {pacman,makepkg}-grawlinson.conf
 ```
 
+* Create a `systemd-nspawn` instance for aurbuild.
+
+```sh
+aur chroot --create \
+  -M /etc/aurutils/makepkg-grawlinson.conf \
+  -C /etc/aurutils/pacman-grawlinson.conf
+```
+
+## Usage
+
+* `make check`: Check for new package versions.
+* `make sync` : Sync local repository with remote.
+* `make` for the rest of the commands.
+
+### Building a new or updated package
+
+```sh
+sh .repo/build [packages ...]
+```
+
+A wrapper around [aurutils][url-aurutils], builds package(s) specified in a
+clean chroot. After successful build, packages are added to the repository
+and old versions are removed. By default, packages and repository database
+are signed.
+
+### Removal
+
+```sh
+sh .repo/remove [packages ...]
+rm -f /var/lib/repo/$REPO/{packages,and,signatures,to,delete}
+```
+
+Removal of package(s) from the repository is invoked via the `.repo/remove`
+script (shown above). Actual deletion of the package(s) (and the
+corresponding package signatures) is to be done manually.
+
 ## Dependencies
 
-- [nvchecker][url-nvchecker]
-- [aurutils][url-aurutils]
-- [rsync][url-rsync]
-- [pass][url-pass]
+### Required
 
-### Also useful
+* [nvchecker][url-nvchecker]
+* [aurutils][url-aurutils]
+* [rsync][url-rsync]
+* [pass][url-pass]
 
-- [pacman-contrib][url-pacman-contrib]
-- [pacutils][url-pacutils]
-- [namcap][url-namcap]
-- [expac][url-expac]
+### Optional
+
+* [pacman-contrib][url-pacman-contrib]
+* [pacutils][url-pacutils]
+* [namcap][url-namcap]
+* [expac][url-expac]
 
 ## References
 
-- [Developer Wiki: Building in a clean chroot](https://wiki.archlinux.org/index.php/DeveloperWiki:Building_in_a_clean_chroot)
-- [GitHub: mdaffin/arch-pkgs](https://github.com/mdaffin/arch-pkgs)
+* [Developer Wiki: Building in a clean chroot](https://wiki.archlinux.org/index.php/DeveloperWiki:Building_in_a_clean_chroot)
+* [GitHub: mdaffin/arch-pkgs](https://github.com/mdaffin/arch-pkgs)
 
 [url-nvchecker]:https://github.com/lilydjwg/nvchecker
 [url-aurutils]:https://github.com/AladW/aurutils