diff --git a/lib/puppet/type/file/ensure.rb b/lib/puppet/type/file/ensure.rb
index 4a68551ee..99652ecc6 100755
--- a/lib/puppet/type/file/ensure.rb
+++ b/lib/puppet/type/file/ensure.rb
@@ -1,170 +1,164 @@
 module Puppet
   Puppet::Type.type(:file).ensurable do
     require 'etc'
     desc "Whether to create files that don't currently exist.
       Possible values are *absent*, *present*, *file*, and *directory*.
       Specifying `present` will match any form of file existence, and
       if the file is missing will create an empty file. Specifying
       `absent` will delete the file (and directory if recurse => true).
 
-      Anything other than those values will be considered to be a symlink.
-      For instance, the following text creates a link:
+      Anything other than those values will create a symlink. In the interest of readability and clarity, you should use `ensure => link` and explicitly specify a
+      target; however, if a `target` attribute isn't provided, the value of the `ensure`
+      attribute will be used as the symlink target:
 
-          # Useful on solaris
+          # (Useful on Solaris)
+          # Less maintainable: 
           file { \"/etc/inetd.conf\":
-            ensure => \"/etc/inet/inetd.conf\"
+            ensure => \"/etc/inet/inetd.conf\",
           }
 
-      You can make relative links:
-
-          # Useful on solaris
+          # More maintainable:
           file { \"/etc/inetd.conf\":
-            ensure => \"inet/inetd.conf\"
+            ensure => link,
+            target => \"/etc/inet/inetd.conf\",
           }
-
-      If you need to make a relative link to a file named the same
-      as one of the valid values, you must prefix it with `./` or
-      something similar.
-
-      You can also make recursive symlinks, which will create a
-      directory structure that maps to the target directory,
-      with directories corresponding to each directory
-      and links corresponding to each file."
+      
+      These two declarations are equivalent."
 
     # Most 'ensure' properties have a default, but with files we, um, don't.
     nodefault
 
     newvalue(:absent) do
       File.unlink(@resource[:path])
     end
 
     aliasvalue(:false, :absent)
 
     newvalue(:file, :event => :file_created) do
       # Make sure we're not managing the content some other way
       if property = @resource.property(:content)
         property.sync
       else
         @resource.write(:ensure)
         mode = @resource.should(:mode)
       end
     end
 
     #aliasvalue(:present, :file)
     newvalue(:present, :event => :file_created) do
       # Make a file if they want something, but this will match almost
       # anything.
       set_file
     end
 
     newvalue(:directory, :event => :directory_created) do
       mode = @resource.should(:mode)
       parent = File.dirname(@resource[:path])
       unless FileTest.exists? parent
         raise Puppet::Error,
           "Cannot create #{@resource[:path]}; parent directory #{parent} does not exist"
       end
       if mode
         Puppet::Util.withumask(000) do
           Dir.mkdir(@resource[:path], mode.to_i(8))
         end
       else
         Dir.mkdir(@resource[:path])
       end
       @resource.send(:property_fix)
       return :directory_created
     end
 
 
     newvalue(:link, :event => :link_created) do
       fail "Cannot create a symlink without a target" unless property = resource.property(:target)
       property.retrieve
       property.mklink
     end
 
     # Symlinks.
     newvalue(/./) do
       # This code never gets executed.  We need the regex to support
       # specifying it, but the work is done in the 'symlink' code block.
     end
 
     munge do |value|
       value = super(value)
       value,resource[:target] = :link,value unless value.is_a? Symbol
       resource[:links] = :manage if value == :link and resource[:links] != :follow
       value
     end
 
     def change_to_s(currentvalue, newvalue)
       return super unless newvalue.to_s == "file"
 
       return super unless property = @resource.property(:content)
 
       # We know that content is out of sync if we're here, because
       # it's essentially equivalent to 'ensure' in the transaction.
       if source = @resource.parameter(:source)
         should = source.checksum
       else
         should = property.should
       end
       if should == :absent
         is = property.retrieve
       else
         is = :absent
       end
 
       property.change_to_s(is, should)
     end
 
     # Check that we can actually create anything
     def check
       basedir = File.dirname(@resource[:path])
 
       if ! FileTest.exists?(basedir)
         raise Puppet::Error,
           "Can not create #{@resource.title}; parent directory does not exist"
       elsif ! FileTest.directory?(basedir)
         raise Puppet::Error,
           "Can not create #{@resource.title}; #{dirname} is not a directory"
       end
     end
 
     # We have to treat :present specially, because it works with any
     # type of file.
     def insync?(currentvalue)
       unless currentvalue == :absent or resource.replace?
         return true
       end
 
       if self.should == :present
         return !(currentvalue.nil? or currentvalue == :absent)
       else
         return super(currentvalue)
       end
     end
 
     def retrieve
       if stat = @resource.stat(false)
         return stat.ftype.intern
       else
         if self.should == :false
           return :false
         else
           return :absent
         end
       end
     end
 
     def sync
       @resource.remove_existing(self.should)
       if self.should == :absent
         return :file_removed
       end
 
       event = super
 
       event
     end
   end
 end
 
diff --git a/lib/puppet/type/file/target.rb b/lib/puppet/type/file/target.rb
index b9fe9213b..7d391e672 100644
--- a/lib/puppet/type/file/target.rb
+++ b/lib/puppet/type/file/target.rb
@@ -1,74 +1,87 @@
 module Puppet
   Puppet::Type.type(:file).newproperty(:target) do
     desc "The target for creating a link.  Currently, symlinks are the
-      only type supported."
+      only type supported.
+      
+      You can make relative links:
+
+          # (Useful on Solaris)
+          file { \"/etc/inetd.conf\":
+            ensure => link,
+            target => \"inet/inetd.conf\",
+          }
+    
+      You can also make recursive symlinks, which will create a
+      directory structure that maps to the target directory,
+      with directories corresponding to each directory
+      and links corresponding to each file."
 
     newvalue(:notlink) do
       # We do nothing if the value is absent
       return :nochange
     end
 
     # Anything else, basically
     newvalue(/./) do
       @resource[:ensure] = :link if ! @resource.should(:ensure)
 
       # Only call mklink if ensure didn't call us in the first place.
       currentensure  = @resource.property(:ensure).retrieve
       mklink if @resource.property(:ensure).safe_insync?(currentensure)
     end
 
     # Create our link.
     def mklink
       raise Puppet::Error, "Cannot symlink on Microsoft Windows" if Puppet.features.microsoft_windows?
 
       target = self.should
 
       # Clean up any existing objects.  The argument is just for logging,
       # it doesn't determine what's removed.
       @resource.remove_existing(target)
 
       raise Puppet::Error, "Could not remove existing file" if FileTest.exists?(@resource[:path])
 
       Dir.chdir(File.dirname(@resource[:path])) do
         Puppet::Util::SUIDManager.asuser(@resource.asuser) do
           mode = @resource.should(:mode)
           if mode
             Puppet::Util.withumask(000) do
               File.symlink(target, @resource[:path])
             end
           else
             File.symlink(target, @resource[:path])
           end
         end
 
         @resource.send(:property_fix)
 
         :link_created
       end
     end
 
     def insync?(currentvalue)
       if [:nochange, :notlink].include?(self.should) or @resource.recurse?
         return true
       elsif ! @resource.replace? and File.exists?(@resource[:path])
         return true
       else
         return super(currentvalue)
       end
     end
 
 
     def retrieve
       if stat = @resource.stat
         if stat.ftype == "link"
           return File.readlink(@resource[:path])
         else
           return :notlink
         end
       else
         return :absent
       end
     end
   end
 end