update Readme to cover adding man pages

Readme.md

@@ -1,6 +1,7 @@
-# dot
+# dotfiles
 
-Manage your personal dotfiles with [GNU Stow](https://www.gnu.org/software/stow/manual/stow.html).
+Manage your personal dotfiles with [GNU
+Stow](https://www.gnu.org/software/stow/manual/stow.html).
 
 GNU Stow can be used directly, but a helper script `./dot` is provided to easy
 the syntax and to support my custom package [Target](#targets) feature.
@@ -9,63 +10,86 @@ This is a Linux first design, but there is rudimentry support for Windows.
 
 > Windows users should use the `./dot.ps1` script instead of the `./dot` script.
 >
-> As GNU Stow is currently unavailable on Windows, `./park.ps1` provides bare minimum functionality for the `./dot.ps1` Windows implementation.
+> As GNU Stow is currently unavailable on Windows, `./park.ps1` provides bare
+> minimum functionality for the `./dot.ps1` Windows implementation.
 
 ## Usage
 
 Keep your dotfiles in your git repo and symlink them into the correct place, allowing you to edit them without forgetting to copy those changes back into your repo.
 
 Further, you can apply your dotfiles to another system by simply checking out your dotfiles repo and running:
+
 ```bash
 ./dot apply <package>
 ```
-Any existing dotfiles on the system will be left as is. So there is no risk of accidentally clobbering untracked dotfiles.
-> NOTE: because clobbering existing dotfiles is avoided, you will have to manually delete or move existing config files out of the way. This only applies to files with same name and location as those in your dotfiles repo. Any other unrelated files (even in the same directory) can co-exist just fine.
+Any existing dotfiles on the system will be left as is. So there is no risk of
+accidentally clobbering untracked dotfiles.
+> NOTE: because clobbering existing dotfiles is avoided, you will have to
+> manually delete or move existing config files out of the way. This only
+> applies to files with same name and location as those in your dotfiles repo.
+> Any other unrelated files (even in the same directory) can co-exist just fine.
 
 Your applied config can be cleaned up by running:
+
 ```bash
 ./dot remove <package>
 ```
-This removes the symlinks to your dotfiles that were previously applied effictively wiping your config.
+This removes the symlinks to your dotfiles that were previously applied
+effictively wiping your config.
 
-Only symlinks to your config files are created, and only symlinks are removed. Therefore there is no risk of losing any changes you may have made since you applied your config.
+Only symlinks to your config files are created, and only symlinks are removed.
+Therefore there is no risk of losing any changes you may have made since you
+applied your config.
 
 ## Repo Structure
 
-The files here are structured for compatibility with [GNU Stow](https://www.gnu.org/software/stow/manual/stow.html) to keep things as
+The files here are structured for compatibility with [GNU
+Stow](https://www.gnu.org/software/stow/manual/stow.html) to keep things as
 simple as possible and reduce reliance on custom logic.
 
-You can package you dotfiles however you like, either by program or a collection of programs.
+You can package you dotfiles however you like, either by program or a collection
+of programs.
 
-[Packages](#packages) that require config files in multiple locations are supported, so you don't have to jump through hoops to keep all your config in a single file or directory.
+[Packages](#packages) that require config files in multiple locations are
+supported, so you don't have to jump through hoops to keep all your config in a
+single file or directory.
 
 You can optionally apply only part of your config depending on requirements:
+
 ```bash
 ./dot apply <package> system
 ```
+
 ```bash
 ./dot apply <package> user
 ```
 
 # Packages
 
-A package is simply a collection of dotfiles (or any config file) that should be applied together.
+A package is simply a collection of dotfiles (or any config file) that should be
+applied together.
 
-For added flexability, a package may also contain one or more [targets](#targets).
+For added flexability, a package may also contain one or more
+[targets](#targets).
 
 ## Package Structrue
 
-All config files for a specific package are kept together in a top level subdirectory of the repo.
+All config files for a specific package are kept together in a top level
+subdirectory of the repo.
 
-The directory structure of each package [target](#targets) is compatible with GNU stow.
+The directory structure of each package [target](#targets) is compatible with
+GNU stow.
 
-A package is therefore simply one of thes top level directories and can consist of a config for one or more programs depending on your needs.
+A package is therefore simply one of thes top level directories and can consist
+of a config for one or more programs depending on your needs.
 
 ## Exampe Repo Structure
 
-When discussing how package [targets](#targets) are handled, the following repo structure will be assumed:
+When discussing how package [targets](#targets) are handled, the following repo
+structure will be assumed:
 
 *Example* with dotfiles repo checked out to `./dotfiles` (`DOTFILES_DIR`):
+
 ```plain
 ./dotfiles
 ├── Readme.md
@@ -82,37 +106,47 @@ When discussing how package [targets](#targets) are handled, the following repo
     └── .vimrc
 ```
 This shows a repo with two packages:
-* vim - no targets (so is assumed to be a `user` target)
-* ssh - two targets: `system` and `user`
+
+    * vim - no targets (so is assumed to be a `user` target)
+    * ssh - two targets: `system` and `user`
 
 ## The ./dot Script
 
-There is a custom wrapper bash script (useing GNU Stow) that you can use to easily install a config package:
+There is a custom wrapper bash script (useing GNU Stow) that you can use to
+easily install a config package:
 
 *Example* Install the config for the `vim` package:
+
 ```bash
 ./dot apply vim
 ```
 
-Or, if the `vim` package has no other [targets](#targets), you can use GNU Stow directly:
+Or, if the `vim` package has no other [targets](#targets), you can use GNU Stow
+directly:
+
 ```
 stow -t "$HOME" vim
 ```
 > Windows users may use the `park.ps1` script as GNU Stow
 
-Multiple [targets](#targets) are supported in the case a given package has a mix of user config and system config.
+Multiple [targets](#targets) are supported in the case a given package has a mix
+of user config and system config.
 
 *Example* Install only system config for the `ssh` package:
+
 ```bash
 ./dot apply ssh system
 ```
 
 *Example* Install all config for the `ssh` package:
+
 ```bash
 ./dot apply ssh
 ```
 
-You can still use GNU Stow directly, with just a minor tweak to the stow options to support the multi-target directory structure:
+You can still use GNU Stow directly, with just a minor tweak to the stow options
+to support the multi-target directory structure:
+
 ```
 stow -d ssh -t "/" system
 stow -d ssh -t "$HOME" user
@@ -122,11 +156,17 @@ package target is passed as the package name.
 
 # Targets
 
-At risk of improving upon the perfection that is GNU Stow, the concept of package targets is added to handle programs that do not store all config in a single location, or for when you want to keep some config separate depending on the target.
+At risk of improving upon the perfection that is GNU Stow, the concept of
+package targets is added to handle programs that do not store all config in a
+single location, or for when you want to keep some config separate depending on
+the target.
 
-For example, you may want to stow your personal *and* system ssh(d) config on your home computer, but only your personal ssh config on a remote server.
+For example, you may want to stow your personal *and* system ssh(d) config on
+your home computer, but only your personal ssh config on a remote server.
 
-By keeping the system and user config separate (as is typically the case when installed), then you can optionally instruct GNU Stow to apply only one of the targets.
+By keeping the system and user config separate (as is typically the case when
+installed), then you can optionally instruct GNU Stow to apply only one of the
+targets.
 
 Each package may have files that target the system or the user file heirarchy.
 
@@ -135,7 +175,8 @@ Therefore, each package may have a subdirectory containing any of:
    * system
    * user
 
-In the case no target subdirectories are present for a given package, then the target is assumed to be the `user` target.
+In the case no target subdirectories are present for a given package, then the
+target is assumed to be the `user` target.
 
 NOTE: More targets may be added in the future:
 
@@ -145,23 +186,29 @@ NOTE: More targets may be added in the future:
    * system-local (`/usr/local`)
    * system-lib (`/usr/local/lib`)
 
-But for now, `$HOME` and `/` is suffient to cover most use cases whilst keeping the package structure as simple as possible (albeiet with long somewhat redundant paths).
+But for now, `$HOME` and `/` is suffient to cover most use cases whilst keeping
+the package structure as simple as possible (albeiet with long somewhat
+redundant paths).
 
 ## The User Target
 
 All directories under the user target are relative to `$HOME`.
 
 *Example* Stow the `.vimrc` at `$HOME`:
+
 ```bash
 ./dot apply vim
 ```
-Given the [example repo structure](#exampe-repo-structure), the resulting `$HOME` dir will look like:
+Given the [example repo structure](#exampe-repo-structure), the resulting
+`$HOME` dir will look like:
+
 ```
 /home/acme
 └── .vimrc -> ./path/to/dotfiles/vim/.vimrc
 ```
 
 On a GNU Stow compatible system this is equivalent to:
+
 ```bash
 stow -d "$DOTFILES_DIR" -t "/home/$USER" vim
 ```
@@ -171,10 +218,14 @@ stow -d "$DOTFILES_DIR" -t "/home/$USER" vim
 All directories under the system targt are relative to `/`.
 
 *Example* Stow system/user `ssh` config at `$HOME` and `/` respectively:
+
 ```bash
 ./dot apply ssh
+
 ```
-Given the [example repo structure](#exampe-repo-structure), the resulting `$HOME` and `/` dir will look like:
+Given the [example repo structure](#exampe-repo-structure), the resulting
+`$HOME` and `/` dir will look like:
+
 ```
 /home/acme
 └── .ssh
@@ -188,8 +239,12 @@ Given the [example repo structure](#exampe-repo-structure), the resulting `$HOME
     ├── ssh_config.d
     └── sshd_config -> ./path/to/dotfiles/ssh/system/etc/ssh/sshd_config
 ```
-> NOTE: given that one of the ssh [package](#packages) targets is a `system` target, you will likely need to run `./dot` as root. In most cases, this should be fine as the files created will be symlinks, so permissions are not relevant.
-> However, if this is not an option for you, you can apply the `user` and `system` targets separately, requiring only running the `system` target as root.
+> NOTE: given that one of the ssh [package](#packages) targets is a `system`
+> target, you will likely need to run `./dot` as root. In most cases, this
+> should be fine as the files created will be symlinks, so permissions are not
+> relevant.  However, if this is not an option for you, you can apply the `user`
+> and `system` targets separately, requiring only running the `system` target as
+> root.
 
 On GNU Stow compatible system this is equivalent to:
 
@@ -198,6 +253,47 @@ stow -d "$DOTFILES_DIR/ssh" -t "/home/$USER" user
 stow -d "$DOTFILES_DIR/ssh" -t / system # needs root permissions obviously
 ```
 
+# Info
+
+Complex dotfiles packages may benefit from documentation. Particularly packages
+with a system target. In contrast to user targeted packages which often consist
+of a single config file or config directory, a system targeted package will
+typically have files in ``/etc``, ``/usr``, etc. all working together.
+
+In such cases, you may find a man page as an elegant way to include Readme
+style info without the headache of finding a good place to put the documentation
+that won't have adverse affects on the stowed files.
+
+The [example repo structure](#exampe-repo-structure), could be updated to
+include a man page by placing the ``ssh-config.7`` file in the appropriate
+location (under ``/usr/share/man``):
+
+```plain
+./dotfiles
+├── Readme.md
+├── ssh
+│   ├── system
+│   │   └── etc
+│   │       └── ssh
+│   │           ├── ssh_config
+│   │           └── sshd_config
+│   ├── usr
+│   │   └── share
+│   │       └── man
+│   │           └── man7
+│   │                └── ssh-config.7
+│   └── user
+│       └── .ssh
+│           └── config
+└── vim
+    └── .vimrc
+```
+
+Then, once stowed, a user may access the documentation as follows:
+
+```bash
+man ssh-config
+```
 
 # Debug