docs: second ssh docs pass

README.md

@@ -168,16 +168,23 @@ Binaries are in `dist/`.
 
 ### SSH guide for `-P/--publish`
 
-If you already know & use `scp` then `-P/--publish` should Just Work :tm: If
+`distribusi-go` only supports one connection method right now: SSH public key
-not, read on for some tips on how to configure your SSH client to help
+authentication using `ssh-agent`. This is mostly for simplicity, there is a
-`distribusi-go` make SSH connections successfully.
+discussion running [over here] if you'd like to see more methods available.
 
-The simplest way to make sure `distribusi` can make an SSH connection with your
+Let's take a practical example. First, make sure your `ssh-agent` is running
-server is to match a `~/.ssh/config` entry with the `-P <server>:...` server
+and your SSH key is loaded:
-value you pass on the command-line.
 
-If you want to run `./distribusi -p <path> -P varia.zone:/var/www/`, then a
+```
-matching `~/.ssh/config` entry might look like this:
+eval $(ssh-agent -k)
+ssh-add ~/.ssh/<ssh-secret-key-part>
+ssh-add -L # see loaded keys
+```
+
+Now, when you type `-P <server>:...`, `distribusi-go` will look up an entry in
+your `~/.ssh/config` with a matching `<server>` value. I.e. if you want to run
+`./distribusi -p <path> -P varia.zone:/var/www/`, then a matching
+`~/.ssh/config` entry might look like this:
 
 ```ssh
 Host varia.zone
@@ -187,18 +194,10 @@ Host varia.zone
   IdentityFile ~/.ssh/<ssh-secret-key-part>
 ```
 
-This tells `distribusi-go` everything it needs to know to make a successful SSH
+`distribusi-go` will read the `User` and `Port` values from this configuration.
-connection. Run with `-d/--debug` for extra help figuring out what connection
-details are being used.
-
-If you have a secret protected SSH key then make sure you've got a running
-`ssh-agent` and have added the key with the following:
 
-```
+If all else fails, try `-d/--debug` for extra help figuring out what SSH
-eval $(ssh-agent -k)
+connection details are used. You can [open a ticket] and we can try and help.
-ssh-add ~/.ssh/<ssh-secret-key-part>
-ssh-add -L # see loaded keys
-```
 
 [Go]: https://go.dev
 [Pillow]: https://pillow.readthedocs.io/en/stable/installation.html#external-libraries
@@ -207,8 +206,9 @@ ssh-add -L # see loaded keys
 [on go.dev]: https://go.dev/doc/install/source#environment
 [on pkg.go.dev]: https://pkg.go.dev/path/filepath#Match
 [open a ticket]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/new/choose
+[over here]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/4
 [report issues]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/new/choose
+[scp]: https://linux.die.net/man/1/scp
 [the entire listing]: https://vvvvvvaria.org/~decentral1se/distribusi-go/
 [this book]: https://www.gopl.io/
 [this ticket]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/1
-[scp]: https://linux.die.net/man/1/scp