manual: Fix a bunch of typos and docbookisms

Closes: #238
Approved by: cgwalters

docs/manual/adapting-existing.md

@@ -23,7 +23,7 @@ deployment.
 Because OSTree only preserves `/var` across upgrades (each
 deployment's chroot directory will be garbage collected
 eventually), you will need to choose how to handle other
-toplevel writable directories specified by the [Filesystem Hierarchy Standard](http://www.pathname.com/fhs/")
+toplevel writable directories specified by the [Filesystem Hierarchy Standard](http://www.pathname.com/fhs/).
 Your operating system may of course choose
 not to support some of these such as `/usr/local`, but following is the
 recommended set:
@@ -37,9 +37,9 @@ recommended set:
  - `/tmp` → `/sysroot/tmp`
 
 Furthermore, since `/var` is empty by default, your operating system
-will need to dynamically create the <emphasis>targets</emphasis> of
+will need to dynamically create the *targets* of these at boot.  A
-these at boot.  A good way to do this is using `systemd-tmpfiles`, if
+good way to do this is using `systemd-tmpfiles`, if your OS uses
-your OS uses systemd.  For example:
+systemd.  For example:
 
 ```
 d /var/log/journal 0755 root root -
@@ -64,10 +64,10 @@ d /run/media 0755 root root -
 Particularly note here the double indirection of `/home`.  By default,
 each deployment will share the global toplevel `/home` directory on
 the physical root filesystem.  It is then up to higher levels of
-management tools to keep <filename>/etc/passwd</filename> or
+management tools to keep `/etc/passwd` or equivalent synchronized
-equivalent synchronized between operating systems.  Each deployment
+between operating systems.  Each deployment can easily be reconfigured
-can easily be reconfigured to have its own home directory set simply
+to have its own home directory set simply by making `/var/home` a real
-by making `/var/home` a real directory.  </chapter>
+directory.
 
 ## Booting and initramfs technology
 
@@ -144,11 +144,11 @@ these new packages on top.  A command like this:
 
 ```
 ostree commit -b osname/releasename/description
---tree=ref=$osname/releasename/description
+--tree=ref=$osname/$releasename/$description
 --tree=dir=/var/tmp/newpackages.13A8D0/
 ```
 
-will create a new commit in the `$osname/releasename/description`
+will create a new commit in the `$osname/$releasename/$description`
 branch.  The OSTree SHA256 checksum of all the files in
 `/var/tmp/newpackages.13A8D0/` will be computed, but we will not
 re-checksum the present existing tree.  In this layering model,
@@ -156,4 +156,4 @@ earlier directories will take precedence, but files in later layers
 will silently override earlier layers.
 
 Then to actually deploy this tree for the next boot:
-`ostree admin deploy <replaceable>osname/releasename/description`
+`ostree admin deploy $osname/$releasename/$description`

docs/manual/atomic-upgrades.md

@@ -18,7 +18,7 @@ implements this.
 To begin a simple upgrade, OSTree fetches the contents of the ref from
 the remote server.  Suppose we're tracking a ref named
 `exampleos/buildmaster/x86_64-runtime`.  OSTree fetches the URL
-`http://$example.com/repo/refs/exampleos/buildmaster/x86_64-runtime`,
+`http://example.com/repo/refs/exampleos/buildmaster/x86_64-runtime`,
 which contains a SHA256 checksum.  This determines the tree to deploy,
 and `/etc` will be merged from currently booted tree.
 
@@ -35,7 +35,7 @@ we need to perform a deployment.
 
 As mentioned in the introduction, OSTree is also designed to allow a
 model where filesystem trees are computed on the client.  It is
-completely agnostic as to how those trees are generated; hey could be
+completely agnostic as to how those trees are generated; they could be
 computed with traditional packages, packages with post-deployment
 scripts on top, or built by developers directly from revision control
 locally, etc.
@@ -58,7 +58,7 @@ Given a commit to deploy, OSTree first allocates a directory for
 it.  This is of the form `/boot/loader/entries/ostree-$osname-$checksum.$serial.conf`.
 The `$serial` is normally 0, but if a
 given commit is deployed more than once, it will be incremented.
-his is supported because the previous deployment may have
+This is supported because the previous deployment may have
 configuration in `/etc` that we do not want to use or overwrite.
 
 Now that we have a deployment directory, a 3-way merge is
@@ -94,7 +94,7 @@ collected at any point.
 
 ## The /ostree/boot directory
 
-However, we want to optimize for the case where we the set of
+However, we want to optimize for the case where the set of
 kernel/initramfs pairs is the same between both the old and new
 deployment lists.  This happens when doing an upgrade that does not
 include the kernel; think of a simple translation update.  OSTree
@@ -106,11 +106,11 @@ automatically remount read-write just for the portion of time
 necessary to update the bootloader configuration.
 
 To implement this, OSTree also maintains the directory
-`/ostree/boot.<replaceable>bootversion</replaceable>`, which is a set
+`/ostree/boot.$bootversion`, which is a set
 of symbolic links to the deployment directories.  The
-<replaceable>bootversion</replaceable> here must match the version of
+`$bootversion` here must match the version of
 `/boot`.  However, in order to allow atomic transitions of
-<emphasis>this</emphasis> directory, this is also a swapped directory,
+*this* directory, this is also a swapped directory,
 so just like `/boot`, it has a version of `0` or `1` appended.
 
 Each bootloader entry has a special `ostree=` argument which refers to

docs/manual/buildsystem-and-repos.md

@@ -63,7 +63,7 @@ But let's discuss building our own.  If you're just experimenting,
 it's quite easy to start with the command line.  We'll assume for this
 purpose that you have a build process that outputs a directory tree -
 we'll call this tool `$pkginstallroot` (which could be `yum
---installroot` or `dbootstrap`, etc.).
+--installroot` or `debootstrap`, etc.).
 
 Your initial prototype is going to look like:
 
@@ -132,7 +132,7 @@ the desired version).
 Now, to construct our final tree:
 
 ```
-rm exampleos-build -rf
+rm -rf exampleos-build
 for package in bash systemd; do
   ostree --repo=build-repo checkout -U --union exampleos/x86_64/${package} exampleos-build
 done

docs/manual/deployment.md

@@ -54,9 +54,9 @@ to avoid computing checksums on the client by default.
 The deployment should not have a traditional UNIX `/etc`; instead, it
 should include `/usr/etc`.  This is the "default configuration".  When
 OSTree creates a deployment, it performs a 3-way merge using the
-<emphasis>old</emphasis> default configuration, the active system's
+*old* default configuration, the active system's `/etc`, and the new
-`/etc`, and the new default configuration.  In the final filesystem
+default configuration.  In the final filesystem tree for a deployment
-tree for a deployment then, `/etc` is a regular writable directory.
+then, `/etc` is a regular writable directory.
 
 Besides the exceptions of `/var` and `/etc` then, the rest of the
 contents of the tree are checked out as hard links into the
@@ -87,4 +87,4 @@ deployment.
 
 At present, not all bootloaders implement the BootLoaderSpec, so
 OSTree contains code for some of these to regenerate native config
-files (such as `/boot/syslinux/syslinux.conf` based on the entries.
+files (such as `/boot/syslinux/syslinux.conf`) based on the entries.

docs/manual/repo.md

@@ -87,7 +87,7 @@ two different generated filesystem trees.  In this example, the
 "runtime" tree contains just enough to run a basic system, and
 "devel-debug" contains all of the developer tools and debuginfo.
 
-The `ostree` supports a simple syntax using the carat `^` to refer to
+The `ostree` supports a simple syntax using the caret `^` to refer to
 the parent of a given commit.  For example,
 `exampleos/buildmaster/x86_64-runtime^` refers to the previous build,
 and `exampleos/buildmaster/x86_64-runtime^^` refers to the one before