Document the wild hostname(1) issue on OS X

As described in #82, the hostname on OS X can vary:

- The result of hostname(1) can change depending on DHCP settings; by
  default, as you move between networks, your hostname will change.
- The value for `ComputerName` as set in scutil(8) contains values that
  are inappropriate for a directory name (spaces, quotes, and so on),
  and is blank by default.
- The value for `LocalHostName` changes based on DNS and DHCP settings.

Therefore, OS X users are highly encouraged to set a hostname using the
`HOSTNAME` variable in rcrc(5).

1 files changed, 14 insertions, 0 deletions

diff --git a/man/rcm.7.mustache b/man/rcm.7.mustache
index 36dec50..c9da706 100644
--- a/man/rcm.7.mustache
+++ b/man/rcm.7.mustache
@@ -220,6 +220,10 @@ different hostname, you can use the
 flag.
 .Pp
 .Dl mkrc -B eggplant .rcrc
+.Pp
+OS X users should see the
+.Sx BUGS
+section for more details.
 .
 .Sh RATIONALE
 The rcm suite was built as an abstraction over the shell, Ruby, Python,
@@ -246,6 +250,16 @@ is maintained by
 .An "Mike Burns" Aq Mt mburns@thoughtbot.com
 and
 .Lk http://thoughtbot.se thoughtbot
+.Sh BUGS
+For OS X systems, we strongly encourage the use of the
+.Va HOSTNAME
+variable in your
+.Xr rcrc 5 .
+We use the
+.Xr hostname 1
+program to determine the unique identifier for the host. This program is
+not specified by POSIX and can vary by system. On OS X the hostname is
+unpredictable, and can even change as part of the DHCP handshake.
 .Sh CONTRIBUTORS
 .An -split
 {{#contributors}}