Small grammar and instruction updates

Modified a bit of grammar, added a clarifying paragraph or two,
and added a working HOOKS example

Signed-off-by: Christian Hesse <mail@eworm.de>

2 files changed, 62 insertions, 42 deletions

diff --git a/README-dracut.md b/README-dracut.md
index 6039d6f..cb1690c 100644
--- a/README-dracut.md
+++ b/README-dracut.md
@@ -1,13 +1,13 @@
 Full disk encryption with Yubikey (Yubico key) for dracut
 =========================================================
 
-This allows to automatically unlock a LUKS encrypted hard disk from `systemd`-
-enabled initramfs.
+This enables you to automatically unlock a LUKS encrypted filesystem from
+a `systemd`-enabled initramfs.
 
 Requirements
 ------------
 
-To compile and use yubikey full disk encryption you need:
+To compile and use Yubikey full disk encryption you need:
 
 * libyubikey-devel
 * ykpers-devel
@@ -18,6 +18,9 @@ To compile and use yubikey full disk encryption you need:
 * systemd-devel
 * keyutils-libs-devel
 
+Additionally you will need to have `make` and `pkg-config` installed to
+successfully compile.
+
 Build and install
 -----------------
 
@@ -34,7 +37,9 @@ Build command is followed by:
 
 > make install-dracut
 
-This will place files to their desired places in filesystem.
+This will place the files in their desired places in the filesystem.
+Keep in mind that you need `root` privileges for installation, so switch
+user or prepend the last command with `sudo`.
 
 Usage
 -----
@@ -48,10 +53,10 @@ adding a line to `/etc/crypttab`. It should read like:
 
 Usually there is already an entry for your device.
 
-Update `/etc/ykfde.conf` with correct settings. Add `mapping-name` from
-above to `device name` in the `general` section. Then add a new section
-with your key's decimal serial number containing the key slot setting.
-The minimal file should look like this:
+Update `/etc/ykfde.conf` with correct settings. Add the value of
+`mapping-name` from above to `device name` in the `general` section. Then
+add a new section with your key's decimal serial number containing the key
+slot setting. The minimal file should look like this:
 
     [general]
     device name = crypt
@@ -59,21 +64,24 @@ The minimal file should look like this:
     [1234567]
     luks slot = 1
 
-*Be warned*: Do not remove or overwrite your interactive key! Keep that
-for backup and rescue!
+*Be warned*: Do not remove or overwrite your interactive (regular) key!
+Keep that for backup and rescue - LUKS encrypted volumes have a total
+of 8 slots (from 0 to 7).
 
-### key setup
+### Key setup
 
 `ykfde` will read its information from these files and understands some
 additional options. Run `ykfde --help` for details. Then prepare
-the key. Plug it in, make sure it is configured for `HMAC-SHA1`.
-After that run:
+the key. Plug it in and make sure it is configured for `HMAC-SHA1`. This can
+be done with `ykpersonalize` from terminal (package `ykpers`)
+or with GUI application `YubiKey Personalization Tool`. After that, run:
 
 > ykfde
 
 This will store a challenge in `/etc/ykfde.d/` and add a new slot to
-your LUKS device. When `ykfde` asks for a passphrase it requires a valid
-passphrase from available slot.
+your LUKS device based on the `/etc/ykfde.conf` configuration. When
+`ykfde` asks for a passphrase it requires a valid passphrase from a
+previously available slot.
 
 Alternatively, adding a key with second factor (`foo` in this example)
 is as easy:
@@ -101,7 +109,7 @@ Every time you update a challenge and/or a second factor run:
 
 > ykfde-cpio
 
-This will write a cpio archive `/boot/ykfde-challenges.img` containing
+This will write a cpio archive to `/boot/ykfde-challenges.img` containing
 your current challenges. Enable systemd service `ykfde` to do this
 automatically on every boot:
 
@@ -113,14 +121,14 @@ Build the initramfs:
 
 > dracut -f
 
-### boot loader
+### Boot loader
 
-Update you `grub` configuration by running:
+Update your `grub` configuration by running:
 
 > grub2-mkconfig -o /boot/grub/grub.cfg
 
 This will add new boot entry that loads the challenges. With other boot
 loaders make sure to load the cpio archive `/boot/ykfde-challenges.img`
-as additional initramfs.
+as an additional initramfs.
 
 Reboot and have fun!
diff --git a/README-mkinitcpio.md b/README-mkinitcpio.md
index 1d1833a..d7a88dd 100644
--- a/README-mkinitcpio.md
+++ b/README-mkinitcpio.md
@@ -1,13 +1,13 @@
 Full disk encryption with Yubikey (Yubico key) for mkinitcpio
 =============================================================
 
-This allows to automatically unlock a LUKS encrypted hard disk from `systemd`-
-enabled initramfs.
+This enables you to automatically unlock a LUKS encrypted filesystem from
+a `systemd`-enabled initramfs.
 
 Requirements
 ------------
 
-To compile and use yubikey full disk encryption you need:
+To compile and use Yubikey full disk encryption you need:
 
 * [yubikey-personalization](https://github.com/Yubico/yubikey-personalization)
 * [iniparser](http://ndevilla.free.fr/iniparser/)
@@ -20,7 +20,7 @@ To compile and use yubikey full disk encryption you need:
 * [markdown](http://daringfireball.net/projects/markdown/) (HTML documentation)
 * [libarchive](http://www.libarchive.org/) (Update challenge on boot)
 
-Additionally it is expected to have `make` and `pkg-config` around to
+Additionally you will need to have `make` and `pkg-config` installed to
 successfully compile.
 
 Build and install
@@ -34,7 +34,9 @@ followed by:
 
 > make install-mkinitcpio
 
-This will place files to their desired places in filesystem.
+This will place the files in their desired places in the filesystem.
+Keep in mind that you need `root` privileges for installation, so switch
+user or prepend the last command with `sudo`.
 
 Usage
 -----
@@ -46,12 +48,14 @@ adding a line to `/etc/crypttab.initramfs`. It should read like:
 
 > `mapping-name` /dev/`LUKS-device` -
 
-Usually there is already an entry for your device.
+Usually there is already an entry for your device. If you do not already
+have a `systemd`-enabled initramfs, you will need to create this file from
+scratch.
 
-Update `/etc/ykfde.conf` with correct settings. Add `mapping-name` from
-above to `device name` in the `general` section. Then add a new section
-with your key's decimal serial number containing the key slot setting.
-The minimal file should look like this:
+Update `/etc/ykfde.conf` with correct settings. Add the value of
+`mapping-name` from above to `device name` in the `general` section. Then
+add a new section with your key's decimal serial number containing the key
+slot setting. The minimal file should look like this:
 
     [general]
     device name = crypt
@@ -59,21 +63,25 @@ The minimal file should look like this:
     [1234567]
     luks slot = 1
 
-*Be warned*: Do not remove or overwrite your interactive key! Keep that
-for backup and rescue!
+*Be warned*: Do not remove or overwrite your interactive (regular) key!
+Keep that for backup and rescue - LUKS encrypted volumes have a total
+of 8 slots (from 0 to 7).
 
-### key setup
+### Key setup
 
 `ykfde` will read its information from these files and understands some
 additional options. Run `ykfde --help` for details. Then prepare
-the key. Plug it in, make sure it is configured for `HMAC-SHA1`.
-After that run:
+the key. Plug it in and make sure it is configured for `HMAC-SHA1`. This can
+be done with `ykpersonalize` from terminal (package `yubikey-personalization`)
+or with GUI application `YubiKey Personalization Tool` (package
+`yubikey-personalization-gui`). After that, run:
 
 > ykfde
 
 This will store a challenge in `/etc/ykfde.d/` and add a new slot to
-your LUKS device. When `ykfde` asks for a passphrase it requires a valid
-passphrase from available slot.
+your LUKS device based on the `/etc/ykfde.conf` configuration. When
+`ykfde` asks for a passphrase it requires a valid passphrase from a
+previously available slot.
 
 Alternatively, adding a key with second factor (`foo` in this example)
 is as easy:
@@ -101,7 +109,7 @@ Every time you update a challenge and/or a second factor run:
 
 > ykfde-cpio
 
-This will write a cpio archive `/boot/ykfde-challenges.img` containing
+This will write a cpio archive to `/boot/ykfde-challenges.img` containing
 your current challenges. Enable systemd service `ykfde` to do this
 automatically on every boot:
 
@@ -109,20 +117,24 @@ automatically on every boot:
 
 ### mkinitcpio hook `ykfde`
 
-Last add `ykfde` to your hook list in `/etc/mkinitcpio.conf`. You should
+Lastly, add `ykfde` to your hook list in `/etc/mkinitcpio.conf`. You should
 already have `systemd` and `sd-encrypt` there as a `systemd`-enabled
-initramfs is prerequisite. Now rebuild your initramfs with:
+initramfs is prerequisite. A working example config is as follows:
+
+> HOOKS="base systemd keyboard autodetect modconf block ykfde sd-encrypt sd-lvm2 filesystems fsck"
+
+Now rebuild your initramfs with:
 
 > mkinitcpio -p linux
 
-### boot loader
+### Boot loader
 
-Update you `grub` configuration by running:
+Update your `grub` configuration by running:
 
 > grub-mkconfig -o /boot/grub/grub.cfg
 
 This will add new boot entry that loads the challenges. With other boot
 loaders make sure to load the cpio archive `/boot/ykfde-challenges.img`
-as additional initramfs.
+as an additional initramfs.
 
 Reboot and have fun!