Minor edits to README.md (mostly formatting) (#110)

README.md

@@ -30,22 +30,27 @@ make check # optional, requires dejagnu and tcllib
 make install # as root
 ```
 
-These commands installs the completions and helpers, as well as a
-profile.d script that loads `bash_completion` where appropriate. If
-your system does not use the profile.d directory (usually below
-`/etc`) mechanism, i.e. does not automatically source shell scripts in
-it, you can source the `$sysconfdir/profile.d/bash_completion.sh`
+These commands install the completions and helpers, as well as a
+`profile.d` script that loads `bash_completion` where appropriate. 
+
+If your system does not use the `profile.d` directory (usually below
+`/etc`) mechanism—i.e. does not automatically source shell scripts in
+it—you can source the `$sysconfdir/profile.d/bash_completion.sh`
 script in `/etc/bashrc` or `~/.bashrc`.
 
-The profile.d script provides a configuration file hook that can be
+The `profile.d` script provides a configuration file hook that can be
 used to prevent loading `bash_completion` on per user basis when it's
-installed system wide. To do this, turn off programmable completion
-with `shopt -u progcomp` in `$XDG_CONFIG_HOME/bash_completion`
-(`~/.config/bash_completion` if `$XDG_CONFIG_HOME` is not set), and
-turn it back on for example in `~/.bashrc` if you want to use
-programmable completion for other purposes.
+installed system wide. To do this: 
+
+1. Turn off programmable completion with `shopt -u progcomp` in 
+   `$XDG_CONFIG_HOME/bash_completion` (or `~/.config/bash_completion` 
+   if `$XDG_CONFIG_HOME` is not set)
+2. Turn it back on (for example in `~/.bashrc`) if you want to use 
+   programmable completion for other purposes.
+
+### macOS (OS X)
 
-If you're using MacOS X, `/etc/bashrc` is apparently not sourced at
+If you're using macOS (formerly OS X), `/etc/bashrc` is apparently not sourced at
 all. In that case, you can put the `bash_completion` file in `/sw/etc`
 and add the following code to `~/.bash_profile`:
 
@@ -73,62 +78,65 @@ tracing on in it before doing anything else there.
 
 ## Known problems
 
-1. There seems to be some issue with using the bash built-in cd within
+1. There seems to be some issue with using the bash built-in `cd` within
    Makefiles. When invoked as `/bin/sh` within `Makefile`s, bash seems
    to have a problem changing directory via the `cd` command. A
    work-around for this is to define `SHELL=/bin/bash` within your
    `Makefile`. This is believed to be a bug in bash.
 
 2. Many of the completion functions assume GNU versions of the various
-   text utilities that they call (e.g. grep, sed and awk). Your
+   text utilities that they call (e.g. `grep`, `sed`, and `awk`). Your
    mileage may vary.
 
 3. If you are seeing 'unbound variable' warnings from bash when
-   hitting \<Tab>, this is because you have either `set -u` or `set -o
-   nounset` somewhere in your start-up files. This causes bash to flag
-   the use of any uninitialised shell variables as an error.
+   hitting <kbd>&lt;Tab></kbd>, this is because you have either `set -u` 
+   or `set -o nounset` somewhere in your start-up files. This causes bash 
+   to flag the use of any uninitialised shell variables as an error.
 
    Whilst we try to avoid references to uninitialised variables in the
    code, there seem to be at least some cases where bash issues this
    warning even though the variable in question has been initialised.
 
    One place this appears to occur is within the `_muttconffiles()`
-   helper function used by mutt completion, where the function calls
+   helper function used by `mutt` completion, where the function calls
    itself recursively. This seems to confuse bash and it issues
    spurious warnings if `nounset` is set.
 
 
 ## FAQ
 
-Q. The bash completion code inhibits some commands from completing on
+**Q. The bash completion code inhibits some commands from completing on
    files with extensions that are legitimate in my environment. Do I
    have to disable completion for that command in order to complete on
-   the files that I need to?
+   the files that I need to?**
 
 A. No. Use `M-/` to (in the words of the bash man page) attempt file
    name completion on the text to the left of the cursor. This will
    circumvent any file type restrictions put in place by the bash
    completion code.
 
-Q. How can I insert my own local completions without having to
-   reinsert them every time you issue a new release?
+**Q. How can I insert my own local completions without having to
+   reinsert them every time you issue a new release?**
 
 A. Put them in `~/.bash_completion`, which is parsed at the end of the
    main completion script. See also the next question.
 
-Q. I author/maintain package X and would like to maintain my own
+**Q. I author/maintain package X and would like to maintain my own
    completion code for this package. Where should I put it to be sure
-   that interactive bash shells will find it and source it?
+   that interactive bash shells will find it and source it?**
 
 A. Install it in one of the directories pointed to by
-   bash-completion's pkgconfig file variables. There are two
-   alternatives: the recommended one is `completionsdir` (get it with
-   `pkg-config --variable=completionsdir bash-completion`) from which
-   completions are loaded on demand based on invoked commands' names,
+   bash-completion's `pkgconfig` file variables. There are two
+   alternatives: 
+
+   - The recommended directory is `completionsdir`, which you can get with
+   `pkg-config --variable=completionsdir bash-completion`. From this
+   directory, completions are loaded on-demand based on invoked commands' names,
    so be sure to name your completion file accordingly, and to include
-   for example symbolic links in case the file provides completions
-   for more than one command. The other one which is present for
-   backwards compatibility reasons is `compatdir` (get it with
+   (for example) symbolic links in case the file provides completions
+   for more than one command. 
+   - The other directory (which only present for backwards compatibility) 
+     is `compatdir` (get it with
    `pkg-config --variable=compatdir bash-completion`) from which files
    are loaded when `bash_completion` is loaded.
 
@@ -166,39 +174,39 @@ A. Install it in one of the directories pointed to by
      ${BASH_COMPLETION_COMPLETIONSDIR})
    ```
 
-Q. I use CVS in combination with passwordless SSH access to my remote
+**Q. I use CVS in combination with passwordless SSH access to my remote
    repository. How can I have the `cvs` command complete on remotely
-   checked-out files where relevant?
+   checked-out files where relevant?**
 
 A. Define `$COMP_CVS_REMOTE`. Setting this to anything will result in
    the behaviour you would like.
 
-Q. When I'm running a `./configure` script and completion returns a list
+**Q. When I'm running a `./configure` script and completion returns a list
    of long options to me, some of these take a parameter,
-   e.g. `--this-option=DESCRIPTION`.
+   e.g. `--this-option=DESCRIPTION`.**
 
-   Running `./configure --help` lists these descriptions, but
+   **Running `./configure --help` lists these descriptions, but
    everything after the `=` is stripped when returning completions, so
    I don't know what kind of data is expected as a given option's
-   parameter.
+   parameter.**
 
-   Is there a way of getting `./configure` completion to return the
+   **Is there a way of getting `./configure` completion to return the
    entire option string, so that I can see what kind of data is
    required and then simply delete the descriptive text and add my own
-   data?
+   data?**
 
 A. Define `$COMP_CONFIGURE_HINTS`. Setting this to anything will
    result in the behaviour you would like.
 
-Q. When doing tar completion on a file within a tar file like this:
+**Q. When doing tar completion on a file within a tar file like this:**
 
    ```
    tar tzvf foo.tar.gz <Tab>
    ```
 
-   the pathnames contained in the tar file are not displayed
-   correctly. The slashes are removed and everything looks like it's
-   in a single directory. Why is this?
+   **the pathnames contained in the tar file are not displayed
+   correctly. The slashes are removed, and everything looks like it's
+   in a single directory. Why is this?**
 
 A. It's a choice we had to make. bash's programmable completion is
    limited in how it handles the list of possible completions it
@@ -218,8 +226,9 @@ A. It's a choice we had to make. bash's programmable completion is
    contents, define `$COMP_TAR_INTERNAL_PATHS` *before* sourcing
    `bash_completion`.
 
-Q. When completing on a symlink to a directory, bash does not append
-   the trailing `/` and I have to hit \<Tab> again. I don't like this.
+**Q. When completing on a symlink to a directory, bash does not append
+   the trailing `/` and I have to hit <kbd>&lt;Tab></kbd> again. 
+   I don't like this.**
 
 A. This has nothing to do with `bash_completion`. It's the default for
    completing symlinks to directories since bash 2.05a, and was added
@@ -230,8 +239,8 @@ A. This has nothing to do with `bash_completion`. It's the default for
    mark-symlinked-directories on` in your `/etc/inputrc` or
    `~/.inputrc` file.
 
-Q. Completion goes awry when I try to complete on something that contains
-   a colon.
+**Q. Completion goes awry when I try to complete on something that contains
+   a colon.**
 
 A. This is actually a 'feature' of bash. bash recognises a colon as
    starting a new completion token, which is often what you want when
@@ -258,7 +267,7 @@ A. This is actually a 'feature' of bash. bash recognises a colon as
    Unfortunately, there's no way to turn this off. The only thing you
    can do is escape the colons with a backslash.
 
-Q. Why is `rpm` completion so slow with `-q`?
+**Q. Why is `rpm` completion so slow with `-q`?**
 
 A. Probably because the database is being queried every time and this uses a
    lot of memory.
@@ -281,17 +290,17 @@ A. Probably because the database is being queried every time and this uses a
    unless it detects that the database has changed since the file was created,
    in which case it will still use the database to ensure accuracy.
 
-Q. bash-completion interferes with my `command_not_found_handler` function!
+**Q. bash-completion interferes with my `command_not_found_handler` function!**
 
 A. If your `command_not_found_handler` function is not intended to
    address (possibly missing) commands invoked during bash
-   programmable completion functions, you can take that into account
-   in your function for example by testing if the `$COMP_`* variables
-   are set and taking appropriate bypass or other action.
+   programmable completion functions, you can account for this
+   by, for example, testing if the `$COMP_`\* variables are set and 
+   taking appropriate bypass or other action.
 
-Q. Can tab completion be made even easier?
+**Q. Can tab completion be made even easier?**
 
-A. The readline(3) library offers a few settings that can make tab
+A. The `readline(3)` library offers a few settings that can make tab
    completion easier (or at least different) to use.
 
    For example, try putting the following in either `/etc/inputrc` or
@@ -309,7 +318,7 @@ A. The readline(3) library offers a few settings that can make tab
    ```
 
    This will suffix each returned file completion with a character
-   denoting its type, in a similar way to ls(1) with `-F` or `--classify`.
+   denoting its type, in a similar way to `ls(1)` with `-F` or `--classify`.
 
    ```
    set page-completions off
@@ -318,7 +327,7 @@ A. The readline(3) library offers a few settings that can make tab
    This turns off the use of the internal pager when returning long
    completion lists.
 
-Q. Is bash the be-all-and-end-all of completion as far as shells go?
+**Q. Is bash the be-all-and-end-all of completion as far as shells go?**
 
 A. Absolutely not. zsh has an extremely sophisticated completion system
    that offers many features absent from the bash implementation. Its