docs: consolidate readme files

.repo/README.md

@@ -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
-```

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
+* Ensure GPG keys for signing packages & repositories have been created,
- clean   remove old packages from local repo
+ and exist in pacman's keyring.
- remove  remove specified package(s) from local repo
+
- sync    sync local repo with remote repo
+* 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]
+### Required
-- [aurutils][url-aurutils]
-- [rsync][url-rsync]
-- [pass][url-pass]
 
-### Also useful
+* [nvchecker][url-nvchecker]
+* [aurutils][url-aurutils]
+* [rsync][url-rsync]
+* [pass][url-pass]
 
-- [pacman-contrib][url-pacman-contrib]
+### Optional
-- [pacutils][url-pacutils]
+
-- [namcap][url-namcap]
+* [pacman-contrib][url-pacman-contrib]
-- [expac][url-expac]
+* [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)
+* [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)
+* [GitHub: mdaffin/arch-pkgs](https://github.com/mdaffin/arch-pkgs)
 
 [url-nvchecker]:https://github.com/lilydjwg/nvchecker
 [url-aurutils]:https://github.com/AladW/aurutils