From 6fe5d1385211e1c8ed5cb2160526e90980a61530 Mon Sep 17 00:00:00 2001
From: Christian <user@example.com>
Date: Fri, 16 Oct 2020 13:25:54 +0200
Subject: [PATCH 1/2] Rewrite docs for building on Linux

Hopefully makes the docs for building on distros without pre-made
packages easier to use.

- Restructure the docs for building into sections for dependencies,
building, and using.
- List packages needed for Ubuntu 20.04.
- Replace code snippets' syntax from text to sh.
- Remove leading $ from code snippets meant for copypasting without
cmd output following.
- Highlight that `pcscd.socket` must be active before using
`yubikey-agent`.
- Add instructions for how to set SSH_AUTH_SOCK if you are using Fish
shell
---
 systemd.md | 84 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 65 insertions(+), 19 deletions(-)

diff --git a/systemd.md b/systemd.md
index 40bd712..1066e64 100644
--- a/systemd.md
+++ b/systemd.md
@@ -5,38 +5,84 @@ provide a yubikey-agent as a package.
 
 Refer to [the README](README) for a list of distributions providing packages.
 
-First, install Go and the [`piv-go` dependencies](https://github.com/go-piv/piv-go#installation), build `yubikey-agent` and place it in `$PATH`.
+## Dependencies
 
-```text
-$ git clone https://filippo.io/yubikey-agent && cd yubikey-agent
-$ go build && sudo cp yubikey-agent /usr/local/bin/
+First, [install Go](https://golang.org/doc/install) and all [dependencies for`piv-go`](https://github.com/go-piv/piv-go#installation).
+Make sure you have a `pinentry` program that works for you, either in the terminal-based or graphical, in `$PATH`.
+
+### Packages for Ubuntu 20.04
+
+`piv-go` requires `libpcsclite-dev` to build and `yubikey-agent` needs `pcscd` to run.
+
+```sh
+sudo apt install -y pcscd libpcsclite-dev
 ```
 
-Make sure you have a `pinentry` program that works for you (terminal-based or graphical) in `$PATH`.
+### `pcscd.socket`
 
-Use `yubikey-agent -setup` to create a new key on the YubiKey.
+Make sure `pcsdc.socket is active before using `yubikey-agent`.
 
-```text
-$ yubikey-agent -setup
+```sh
+$ systemctl is-active pcscd.socket
+active
 ```
 
-Then, create a systemd user service at `~/.config/systemd/user/yubikey-agent.service`
-with the contents of [yubikey-agent.service](contrib/systemd/user/yubikey-agent.service).
+If `pcscd.socket` is not active, you need to start it manually:
+
+```sh
+sudo systemctl enable --now pcscd.socket
+```
 
-Depending on your distribution (`systemd <=239` or no user namespace support),
-you might need to edit the `ExecStart=` line and some of the sandboxing
-options.
+## Building
 
-Refresh systemd, make sure that the PC/SC daemon is available, and start the yubikey-agent.
+Build the `yubikey-agent` and place it somewhere on your `$PATH`, such as `/usr/local/bin/`.
 
-```text
-$ systemctl daemon-reload --user
-$ sudo systemctl enable --now pcscd.socket
-$ systemctl --user enable --now yubikey-agent
+```sh
+git clone https://filippo.io/yubikey-agent
+cd yubikey-agent
+go build
+sudo cp yubikey-agent /usr/local/bin/
 ```
 
-Finally, add the following line to your shell profile and restart it.
+## Creating your first key
 
+After all dependencies are installed and `yubikey-agent` is built, you are ready to start.
+Use `yubikey-agent -setup` to create a new key on your YubiKey.
+
+```sh
+yubikey-agent -setup
 ```
+
+## systemd service
+
+Now we will create a systemd user service for `~/.config/systemd/user/yubikey-agent.service`
+with the contents of [yubikey-agent.service](contrib/systemd/user/yubikey-agent.service).
+
+```sh
+mkdir -p ~/.config/systemd/user/
+cp contrib/systemd/user/yubikey-agent.service ~/.config/systemd/user/yubikey-agent.service
+```
+
+**NB:** _Depending on your distribution (`systemd <=239` or no user namespace support), you might need to edit the `ExecStart=` line and some of the sandboxing options._
+
+Refresh the systemd daemon and start the `yubikey-agent` service.
+
+```sh
+systemctl daemon-reload --user
+systemctl --user enable --now yubikey-agent
+```
+
+To integrate `yubikey-agent` with SSH, set `SSH_AUTH_SOCK` to `yubikey-agent`'s socket. 
+Add the following to your shell profile and restart your shell.
+
+```sh
 export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/yubikey-agent/yubikey-agent.sock"
 ```
+
+### Fish shell
+
+If you use Fish shell, then add the following to `~/.config/fish/config.fish`
+
+```sh
+set SSH_AUTH_SOCK "$XDG_RUNTIME_DIR/yubikey-agent/yubikey-agent.sock"
+```
\ No newline at end of file

From cc51b5b7bfa04f4e30e9bd2cf6f95d83cdb0787f Mon Sep 17 00:00:00 2001
From: Christian <user@example.com>
Date: Fri, 16 Oct 2020 13:34:32 +0200
Subject: [PATCH 2/2] Add missing ` around socket name

---
 systemd.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/systemd.md b/systemd.md
index 1066e64..00dcf35 100644
--- a/systemd.md
+++ b/systemd.md
@@ -20,7 +20,7 @@ sudo apt install -y pcscd libpcsclite-dev
 
 ### `pcscd.socket`
 
-Make sure `pcsdc.socket is active before using `yubikey-agent`.
+Make sure `pcsdc.socket` is active before using `yubikey-agent`.
 
 ```sh
 $ systemctl is-active pcscd.socket