Re-write the tutorial

Thanks to Rebecca Meritz (@rmeritz) for feedback on rcm(7), I have
restructured it and re-written the quick start section. Much of the
details about the sync algorithm have moved into rcup(1).

The new rcm(7) covers a quick start for those with existing directories,
including caveats for `install` scripts, dotted filenames, and
non-~/.dotfiles directory names; a quick start for those without
anything; and motivating sections for "advanced" features like tags,
host-specific files, and multiple directories.

2 files changed, 152 insertions, 138 deletions

diff --git a/man/rcm.7 b/man/rcm.7
index 0033f0f..cd74d1f 100644
--- a/man/rcm.7
+++ b/man/rcm.7
@@ -33,73 +33,118 @@ dotfiles
 .Dc
 because they begin with a period.
 .Pp
-This suite is useful, for example, for commiting your rc files to a
-central repository to share on GitHub, but it also scales to a more
-complex situation such as mutliple source directories shared between
-computers with some host-specific or task-specific files.
+This suite is useful for commiting your rc files to a central repository
+to share on GitHub, but it also scales to a more complex situation such
+as mutliple source directories shared between computers with some
+host-specific or task-specific files.
 .Pp
 This guide serves as a tutorial motivating the suite. For a list of
 quick reference documentation see the
 .Sx SEE ALSO
 section below.
-.
-.Sh QUICK START
-If you do not already have a dotfiles directory then we can get started
-quickly. Use the
-.Xr mkrc 1
-command to add files to the directory.
 .Pp
-.Dl mkrc .vimrc
+The rcm suite was built as an abstraction over the shell, Ruby, Python,
+and make scripts people were writing and sharing. It is intended to run
+on any unix system and support the range from simple to complex dotfile
+directories.
 .Pp
-You can see the effects of this with
+As such, this suite is useful as a common base. Through this we can
+share tools and develop this further as a first-class entity. It is also
+our hope that a common set of tools will encourage others to share their
+dotfiles, too.
+.
+.Sh QUICK START FOR EXISTING DOTFILES DIRECTORIES
+This section is for those who already have an existing dotfiles
+directory; this directory is
+.Pa ~/.dotfiles ;
+the directory only contains rc files; and these rc filenames do not
+begin with a period. See the caveats below if this description is close
+but not quite right.
+.Bl -enum
+.It
+Dryrun with
 .Xr lsrc 1 .
 .Pp
 .Dl lsrc
+.It
+Update any symlinks with
+.Xr rcup 1 .
 .Pp
-The default dotfiles directory is
-.Pa $HOME/.dotfiles .
-The
-.Xr mkrc 1
-command will move
-.Pa .vimrc
-to
-.Pa .dotfiles/vimrc ,
-then symlink
-.Pa .vimrc
-to
-.Pa .dotfiles/vimrc .
+.Dl rcup -v
+.It
+Add new rc files with
+.Xr mkrc 1 .
 .Pp
-This suite becomes more powerful when you share your dotfiles directory
-between computers, either because mutliple people share the same
-directory or because you have mutliple computers. As a quick simulation,
-we can create a file in your new
-.Pa .dotfiles
-directory.
-.Pp
-.Dl echo TAGS="zsh" > ~/.dotfiles/rcrc
-.Pp
-We can update our home directory to have a new
-.Pa .rcrc
-file (a symlink to
-.Pa .dotfiles/rcrc )
-using the
+.Dl mkrc ~/.tigrc
+.El
+.Ss CAVEAT: EXISTING INSTALL SCRIPTS
+Many existing dotfile directories have scripts named
+.Pa install
+or
+.Pa Makefile
+in the directory directory. This will cause a
+.Pa ~/.install
+or
+.Pa ~/.Makefile
+symlink to be created in your home
+directory. The best option here is to move that file outside of your
+dotfiles directory or remove it entirely.
+.Pp
+.Dl rm -f install Rakefile Makefile install.sh
+.Ss CAVEAT: DOTTED FILENAMES IN DOTFILES DIRECTORY
+A less common situation is for all the filenames in your dotfiles
+directory to be prefixed with a period. These files are skipped by the
+rcm suite, and thus would result in nothing happening. The only option
+in this case is to rename all the files, for example by using a shell
+command like the following. Note that this will break any existing
+symlinks.
+.Pp
+.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \;
+.Ss CAVEAT: DOTFILES DIRECTORY NOT IN Pa ~/.dotfiles
+This all assumes that your dotfiles directory is
+.Pa ~/.dotfiles .
+If it is elsewhere and you do not want to move it you can use the
+.Fl d Ar DIR
+option to
+.Xr rcup 1
+or modify
+.Ev DOTFILES_DIRS
+in
+.Xr rcrc 5 .
+.Pp
+.Dl rcup -d configs -v
+.
+.Sh QUICK START FOR BLANK DOTFILES DIRECTORIES
+This section is for those who dot not have an existing dotfiles
+directory and whose dotfiles and normal and just as they were created.
+.Bl -enum
+.It
+Add your rc files to a dotfiles directory with
+.Xr mkrc 1 .
+.Pp
+.Dl mkrc .zshrc .gitconfig .tigrc
+.It
+Synchronize your home directory with
 .Xr rcup 1
-command.
 .Pp
 .Dl rcup -v
+.El
 .Pp
-We passed the
-.Fl v
-option to see in more explicit detail what it
-does. All rcm commands take the
-.Fl v
-option, and mutliple
-.Fl v
-options can be given to give more explicit detail.
-.Pp
-If you do share the dotfiles directory between people, you may end up
-with some irrelevant or even incorrect rc files. For example, you may
-have a
+This will give you a directory named
+.Pa ~/.dotfiles
+with your dotfiles in it. Your original dotfiles will be symlinks into
+this directory. For example,
+.Pa ~/.zshrc
+will be a symlink to
+.Pa ~/.dotfiles/zshrc .
+.
+.Sh TAGGED DOTFILES
+This suite becomes more powerful when you share your dotfiles directory
+between computers, either because multiple people share the same
+directory or because you have mutliple computers.
+.Pp
+If you share the dotfiles directory between people, you may end up with
+some irrelevant or even incorrect rc files. For example, you may have a
 .Pa .zshrc
 while your other contributor has a
 .Pa .bashrc .
@@ -113,7 +158,7 @@ making a
 .Pa tag-zsh
 directory and moving the
 .Pa .zshrc
-into it.
+file into it.
 .Pp
 .Dl mkrc -t zsh .zshrc
 .Pp
@@ -129,14 +174,15 @@ you can pass the
 option to
 include the tags you want. This can also be set in the
 .Xr rcrc 5
-configuration file, as hinted at above.
+configuration file with the
+.Ev TAGS
+variable.
 .Pp
 .Dl rcup -t zsh
-.Pp
-The tags are useful for sharing a single dotfiles directory between
-competers or people, but another common situation is combining multiple
-dotfiles directories that people have shared with you. For this we have
-the
+.
+.Sh MULTIPLE DOTFILE DIRECTORIES
+Another common situation is combining multiple dotfiles directories that
+people have shared with you. For this we have the
 .Fl d
 flag or the
 .Ev DOTFILES_DIRS
@@ -151,7 +197,8 @@ will use the first result, not the last; that is,
 .Pa .dotfiles/vimrc
 will take precedence over
 .Pa marriage-dotfiles/vimrc .
-.Pp
+.
+.Sh HOST-SPECIFIC DOTFILES
 In a similar use case to tags you can also have host-specific files
 marked. This will go by the hostname. The
 .Xr rcrc 5
@@ -161,81 +208,7 @@ file is a popular candidate for a host-specific file.
 .Dl mkdir .dotfiles/host-`hostname`
 .Dl mv .rcrc .dotfiles/host-`hostname`/rcrc
 .Dl rcup -v
-.Pp
-.Sh MIGRATING EXISTING WORKFLOWS
-Many people have existing dotfiles directories, and have been managing
-them using custom scripts. The suite of tools in this package should be
-able to replace your custom scripts with little effort.
-.Pp
-When converting an existing dotfiles directory you do need some
-knowledge of how rcm works and what it expects. Details can be found in
-.Xr rcup 1 ,
-but briefly:
-.Bl -enum
-.It
-All non-host, non-tag files without a dot prefix are symlinked to the
-dotted filename in your home directory. So,
-.Pa .dotfiles/tigrc
-is
-symlinked to
-.Pa ~/.tigrc .
-.It
-All non-host, non-tag directories have their structure copied to your
-home directory, then a non-dotted symlink is created within.  So for
-example,
-.Pa .dotfiles/vim/autoload/haskell.vim
-causes the
-.Pa ~/.vim/autoload
-directory to be created, then
-.Pa haskell.vim
-is symlinked within.
-.It
-Steps (1) and (2) are applied to host-specific files.
-.It
-Steps (1) and (2) are applied to tag-specific files.
-.El
-.Pp
-Two alternative conventions in dotfile directories can cause issue with
-this. The most common problem is to have a file named
-.Pa install
-or
-.Pa Makefile
-in your dotfiles directory. This will cause a
-.Pa ~/.install
-or
-.Pa ~/.Makefile
-symlink to be created in your home
-directory. The best option here is to move that file outside of your
-dotfiles directory, or remove it entirely.
-.Pp
-A less common situation is for all the filenames in your dotfiles
-directory to be prefixed with a period. These files are skipped by the
-rcm suite, and thus would result in nothing happening. The only option
-in this case is to rename all the files, for example by using a shell
-command like the following. Note that this will break any existing
-symlinks.
-.Pp
-.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \;
-.Pp
-The easiest way to see what the rcm suite will do is to run the
-.Xr lsrc 1
-command. This shows all the symlinks that the suite intends
-to maintain.
-.Pp
-Once you are satisfied and ready to try rcm, use the
-.Xr rcup 1
-command.
-.Pp
-.Sh WHY RCM
-The rcm suite was built as an abstraction over the shell, Ruby, Python,
-and make scripts people were writing and sharing. It is intended to run
-on any unix system and support the range from simple to complex dotfile
-directories.
-.Pp
-As such, this suite is useful as a common base. Through this we can
-share tools and develop this further as a first-class entity. It is also
-our hope that a common set of tools will encourage others to share their
-dotfiles, too.
+.
 .Sh FILES
 .Pa ~/.dotfiles
 .Pa ~/.rcrc
diff --git a/man/rcup.1 b/man/rcup.1
index 5f835f0..b4feca4 100644
--- a/man/rcup.1
+++ b/man/rcup.1
@@ -51,8 +51,8 @@ directories.
 Two meta files are supported: host-specific files and tagged files.
 .Pp
 Host-specific files go in a directory named for the host, prefixed with
-.Pa host-
-\&. For example,
+.Pa host- .
+For example,
 .Pa .dotfiles/host-scarlett
 contains files specific to the computer with hostname
 .Pa scarlett
@@ -61,12 +61,53 @@ contains files specific to the computer with hostname
 \&.
 .Pp
 Tagged files go in a directory named for the tag, prefixed with
-.Li tag
-\&. Files under
+.Li tag- .
+Therefore, files under
 .Pa .dotfiles/tag-git
 are only installed when installing using the
 .Li git
 tag.
+.Sh ALGORITHM
+It is instructive to understand the process
+.Nm rcup
+uses when synchronizing your rc files:
+.Bl -enum
+.It
+All non-host, non-tag files without a dot prefix are symlinked to the
+dotted filename in your home directory. So,
+.Pa .dotfiles/tigrc
+is
+symlinked to
+.Pa ~/.tigrc .
+.It
+All non-host, non-tag directories have their structure copied to your
+home directory, then a non-dotted symlink is created within.  So for
+example,
+.Pa .dotfiles/vim/autoload/haskell.vim
+causes the
+.Pa ~/.vim/autoload
+directory to be created, then
+.Pa haskell.vim
+is symlinked within.
+.It
+Steps (1) and (2) are applied to host-specific files. These are files
+under a directory named
+.Sm off
+.Pa host- Va $HOSTNAME .
+.Sm on
+.It
+Steps (1) and (2) are applied to tag-specific files. These are files
+under directories named
+.Sm off
+.Pa tag- Va $TAG_NAME ,
+.Sm on
+where
+.Va $TAG_NAME
+is the name of each specified tag in turn, taken from the command line
+or from
+.Xr rcrc 5 .
+.El
+.
 .Sh FILES
 .Pa ~/.dotfiles
 .Pa ~/.rcrc