From dd802fd3ece848d35c8e500e8170924ad90ad64c Mon Sep 17 00:00:00 2001
From: Mike Burns <mike@mike-burns.com>
Date: Wed, 31 Jul 2013 08:23:07 -0400
Subject: 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.
---
 man/rcup.1 | 49 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 45 insertions(+), 4 deletions(-)

(limited to 'man/rcup.1')

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
-- 
cgit v1.2.3