Re: [PATCH] doc: note the relationship between realpath and readlink

[Pádraig Brady]

On 09/02/17 01:43, Dmitry V. Levin wrote:
> On Wed, Feb 08, 2017 at 09:04:38PM -0800, Pádraig Brady wrote:
>> Now that `realpath` is widely available, recommend it
>> over the less cross compatible `readlink -f`.
> 
> I'm not sure there is enough evidence to make this statement about
> compatibility.  Wouldn't it be better to use a different rationale?
> 
>> * doc/coreutils.texi (realpath invocation): Mention why realpath
>> is the preferred command for canonicalization.
>> (readlink invocation): Recommend realpath for canonicalization.
>> * man/readlink.x: Likewise.
>> ---
>>  doc/coreutils.texi | 9 ++++++++-
>>  man/readlink.x     | 2 ++
>>  2 files changed, 10 insertions(+), 1 deletion(-)
>>
>> diff --git a/doc/coreutils.texi b/doc/coreutils.texi
>> index 629136b..4935b80 100644
>> --- a/doc/coreutils.texi
>> +++ b/doc/coreutils.texi
>> @@ -10260,7 +10260,8 @@ of a symbolic link, it produces no output and exits 
>> with a nonzero exit code.
>>  
>>  @command{readlink} outputs the absolute name of the given files which 
>> contain
>>  no @file{.}, @file{..} components nor any repeated separators
>> -(@file{/}) or symbolic links.
>> +(@file{/}) or symbolic links.  Note the @command{realpath} command is the
>> +preferred command to use for canonicalization.  @xref{realpath invocation}
>>  
>>  @end table
>>  
>> @@ -13685,6 +13686,12 @@ all but the last component of the specified files 
>> must exist.  Synopsis:
>>  realpath [@var{option}]@dots{} @var{file}@dots{}
>>  @end example
>>  
>> +The file name canonicalization functionality overlaps with that of the
>> +@command{readlink} command, but this is the preferred command for
> 
> Why this contradicting "but"?

True, fixed.

>> +canonicalization as it's a more suitable command name, and its syntax
>> +is more compatible across systems.  In addition this command supports
>> +relative file name processing functionality.
> 
> Again, I'm not sure there is enough evidence to make this statement about
> compatibility.  As realpath has all canonicalization functionality of
> readlink plus some of its own, this should be enough to recommend realpath
> over readlink for canonicalization.

I was getting at `readlink` on macOS not supporting -f,
while realpath is available on FreeBSD and macOS ports with
a compatible albeit a subset interface.
But yes the main reason is that "realpath" is the more standard name
for this whether at the command line, library call, in python, etc.

thanks,
Pádraig