From 9c02bcc5c31a74b813c2ad623d69284f7b1dce50 Mon Sep 17 00:00:00 2001 From: Mike Burns Date: Thu, 1 Aug 2013 08:20:54 -0400 Subject: Incorporate final round of rcm(7) feedback Some good suggestions from Rebecca Meritz (@rmeritz) again, including having the tag, host, and multiple dirs sections use enumerated lists like the quick start sections, and using the phrase "common problems" instead of "caveats". --- man/rcm.7 | 77 +++++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 43 insertions(+), 34 deletions(-) diff --git a/man/rcm.7 b/man/rcm.7 index cd74d1f..5ad2dea 100644 --- a/man/rcm.7 +++ b/man/rcm.7 @@ -34,50 +34,45 @@ dotfiles because they begin with a period. .Pp 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 +to share, 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. -.Pp -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 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. +begin with a period. See the caveats below if this is not you. .Bl -enum .It Dryrun with .Xr lsrc 1 . +Look for anything unexpected in here, such as +.Pa ~/.install +or +.Pa ~/.Makefile , +or an empty list of dotfiles. .Pp .Dl lsrc .It Update any symlinks with .Xr rcup 1 . +This is likely to do nothing, since your dotfiles already exist. .Pp .Dl rcup -v .It -Add new rc files with +When necessary, add new rc files with .Xr mkrc 1 . .Pp .Dl mkrc ~/.tigrc .El -.Ss CAVEAT: EXISTING INSTALL SCRIPTS +.Ss COMMON PROBLEM: EXISTING INSTALL SCRIPTS Many existing dotfile directories have scripts named .Pa install or @@ -91,7 +86,7 @@ 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 +.Ss COMMON PROBLEM: 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 @@ -100,7 +95,7 @@ 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 +.Ss COMMON PROBLEM: 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 @@ -116,7 +111,7 @@ in . .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. +directory and whose dotfiles are standard. .Bl -enum .It Add your rc files to a dotfiles directory with @@ -149,7 +144,8 @@ some irrelevant or even incorrect rc files. For example, you may have a while your other contributor has a .Pa .bashrc . This situation can be handled with tags. -.Pp +.Bl -enum +.It A tag is a directory under the dotfiles directory the starts with the letters .Li tag- . @@ -158,15 +154,14 @@ making a .Pa tag-zsh directory and moving the .Pa .zshrc -file into it. +file into it using +.Xr mkrc 1 +and passing the +.Fl t +option. .Pp .Dl mkrc -t zsh .zshrc -.Pp -And likewise, your dotfiles partner would do the same for -.Pa .bashrc . -.Pp -.Dl mkrc -t bash .bashrc -.Pp +.It When updating with .Xr rcup 1 you can pass the @@ -179,6 +174,7 @@ configuration file with the variable. .Pp .Dl rcup -t zsh +.El . .Sh MULTIPLE DOTFILE DIRECTORIES Another common situation is combining multiple dotfiles directories that @@ -189,26 +185,39 @@ flag or the option in .Pa .rcrc . .Pp -.Dl rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles -.Pp -This rcup invocation will go in sequence through the three dotfiles +The following 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, .Pa .dotfiles/vimrc will take precedence over .Pa marriage-dotfiles/vimrc . +.Pp +.Dl rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles +.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 +You can also mark host-specific files. This will go by the hostname. The .Xr rcrc 5 configuration -file is a popular candidate for a host-specific file. +file is a popular candidate for a host-specific file, since the tags and +dotfile directories listed in there are often specific to a single +machine. .Pp .Dl mkdir .dotfiles/host-`hostname` .Dl mv .rcrc .dotfiles/host-`hostname`/rcrc -.Dl rcup -v +.Dl rcup . +.Sh RATIONALE +.Pp +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 -- cgit v1.2.3