Add tutorial-style documentation: rcm(7)

Add a manpage with a tutorial, named `rcm`. This covers how to get
started from nothing, how to convert an existing dotfiles directory, and
why to use suite at all.

4 files changed, 174 insertions, 3 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index 6b6b1b5..766c24c 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1 +1 @@
-man_MANS = lsrc.1  mkrc.1  rcrc.5  rcup.1
+man_MANS = lsrc.1  mkrc.1  rcrc.5  rcup.1 rcm.7
diff --git a/man/Makefile.in b/man/Makefile.in
index 07d55cf..a1b10d7 100644
--- a/man/Makefile.in
+++ b/man/Makefile.in
@@ -169,7 +169,7 @@ target_alias = @target_alias@
 top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
-man_MANS = lsrc.1  mkrc.1  rcrc.5  rcup.1
+man_MANS = lsrc.1  mkrc.1  rcrc.5  rcup.1 rcm.7
 all: all-am
 
 .SUFFIXES:
diff --git a/man/rcm.7 b/man/rcm.7
new file mode 100644
index 0000000..46fb3de
--- /dev/null
+++ b/man/rcm.7
@@ -0,0 +1,171 @@
+.TH rcm "7" "July 2013" "rcm"
+
+.SH NAME
+rcm \- dotfile management
+
+.SH DESCRIPTION
+
+The rcm suite of tools is for managing dotfiles directories. This is a
+directory containing all the \fI.*rc\fR files in your home directory
+(\fI.zshrc\fR, \fI.vimrc\fR, and so on). These files have gone by many
+names in history, such as \fIrc files\fR because they typically end in
+\fBrc\fR  or \fIdotfiles\fR because they begin with a period.
+
+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 guide serves as a tutorial motivating the suite. For a list of
+quick reference documentation see the \fBSEE ALSO\fR section below.
+
+.SH QUICK START
+
+If you do not already have a dotfiles directory then we can get started
+quickly. Use the \fImkrc\fR\|(1) command to add files to the directory.
+
+.B mkrc .vimrc
+
+You can see the effects of this with \fIlsrc\fR\|(1).
+
+.B lsrc
+
+The default dotfiles directory is \fB$HOME/.dotfiles\fR\|. The
+\fImkrc\fR command will move \fB.vimrc\fR to \fB.dotfiles/vimrc\fR, then
+symlink \fB.vimrc\fR to \fBdotfiles/vimrc\fR\|.
+
+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 \fB.dotfiles\fR directory.
+
+.B echo TAGS="zsh" > ~/.dotfiles/rcrc
+
+We can update our home directory to have a new \fB.rcrc\fR file (a
+symlink to \fB.dotfiles/rcrc\fR\|) using the \fIrcup\fR\|(1) command.
+
+.B rcup -v
+
+We passed the \fB-v\fR option to see in more explicit detail what it
+does. All rcm commands take the \fB-v\fR option, and mutliple \fB-v\fR
+options can be given to give more explicit detail.
+
+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 \fB.zshrc\fR while your other contributor has a \fB.bashrc\fR\|.
+This situation can be handled with tags.
+
+A tag is a directory under the dotfiles directory the starts with the
+letters \fBtag-\fR\|. We can handle the competing shell example by
+making a \fBtag-zsh\fR directory and moving the \fB.zshrc\fR into it.
+
+.B mkrc -t zsh .zshrc
+
+And likewise, your dotfiles partner would do the same for
+\fB.bashrc\fR\|.
+
+.B mkrc -t bash .bashrc
+
+When updating with \fIrcup\fR you can pass the \fB-t\fR option to
+include the tags you want. This can also be set in the \fBrcrc\fR\|(5)
+configuration file, as hinted at above.
+
+.B rcup -t zsh
+
+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 \fB-d\fR flag or the \fBDOTFILES_DIRS\fR option in \fB.rcrc\fR\|.
+
+.B rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles
+
+This rcup invocation will go in sequence through the three dotfiles
+directories, updating any symlinks as needed. Any overlapping rc files
+will use the first result, not the last; that is, \fB.dotfiles/vimrc\fR
+will take precedence over \fBmarriage-dotfiles/vimrc\fR\|.
+
+In a similar use case to tags you can also have host-specific files
+marked. This will go by the hostname. The \fBrcrc\fR\|(5) configuration
+file is a popular candidate for a host-specific file.
+
+.B mkdir .dotfiles/host-`hostname`
+.P
+.B mv .rcrc .dotfiles/host-`hostname`/rcrc
+.P
+.B rcup -v
+
+.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.
+
+When converting an existing dotfiles directory you do need some
+knowledge of how rcm works and what it expects. Details can be found in
+\fIrcup\fR\|(1), but briefly:
+
+.TP
+1
+All non-host, non-tag files without a dot prefix are symlinked to the
+dotted filename in your home directory. So, \fB.dotfiles/tigrc\fR is
+symlinked to \fB~/.tigrc\fR\|.
+
+.TP
+2
+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, \fB.dotfiles/vim/autoload/haskell.vim\fR causes the
+\fB~/.vim/autoload\fR directory to be created, then \fBhaskell.vim\fR is
+symlinked within.
+
+.TP
+3
+Steps (1) and (2) are applied to host-specific files.
+
+.TP
+4
+Steps (1) and (2) are applied to tag-specific files.
+
+.PP
+
+Two alternative conventions in dotfile directories can cause issue with
+this. The most common problem is to have a file named \fBinstall\fR or
+\fBMakefile\fR in your dotfiles directory. This will cause a
+\fB~/.install\fR or \fB~/.Makefile\fR 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.
+
+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.
+
+.B find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \;
+
+The easiest way to see what the rcm suite will do is to run the
+\fIlsrc\fR\|(1) command. This shows all the symlinks that the suite intends
+to maintain.
+
+Once you are satisfied and ready to try rcm, use the \fIrcup\fR command.
+
+.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.
+
+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 SEE ALSO
+
+\&\fImkrc\fR\|(1), \fIrcup\fR\|(1), \fIlsrc\fR\|(1), \fIrcrc\fR\|(5)
+
+.SH AUTHOR
+
+Written by Mike Burns.
diff --git a/man/rcrc.5 b/man/rcrc.5
index 6f28e06..2f9e02a 100644
--- a/man/rcrc.5
+++ b/man/rcrc.5
@@ -37,4 +37,4 @@ Written by Mike Burns.
 
 .SH SEE ALSO
 
-\&\fImkrc\fR\|(5), \fIrcup\fR\|(1), \fIlsrc\fR\|(1)
+\&\fImkrc\fR\|(1), \fIrcup\fR\|(1), \fIlsrc\fR\|(1)