[PATCH] Correct docstring of 'symlink'

[PATCH] Correct docstring of 'symlink'

[Taylan Ulrich Bayırlı/Kammer]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: patch --]
[-- Type: text/x-diff, Size: 1071 bytes --]

From 613c00221bf4e2bd5e809aebd792ed7c056455b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Taylan=20Ulrich=20Bay=C4=B1rl=C4=B1/Kammer?=
 <taylanbayirli@gmail.com>
Date: Fri, 20 Feb 2015 21:11:03 +0100
Subject: [PATCH] Correct docstring of 'symlink'

* libguile/filesys.c (symlink): Correct the docstring, which had
  'oldpath' and 'newpath' confused.
---
 libguile/filesys.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libguile/filesys.c b/libguile/filesys.c
index b473af8..48232e8 100644
--- a/libguile/filesys.c
+++ b/libguile/filesys.c
@@ -991,8 +991,8 @@ SCM_DEFINE (scm_fsync, "fsync", 1, 0, 0,
 #ifdef HAVE_SYMLINK
 SCM_DEFINE (scm_symlink, "symlink", 2, 0, 0,
             (SCM oldpath, SCM newpath),
-	    "Create a symbolic link named @var{oldpath} with the value\n"
-	    "(i.e., pointing to) @var{newpath}.  The return value is\n"
+	    "Create a symbolic link named @var{newpath} with the value\n"
+	    "(i.e., pointing to) @var{oldpath}.  The return value is\n"
 	    "unspecified.")
 #define FUNC_NAME s_scm_symlink
 {
-- 
2.2.1

Re: [PATCH] Correct docstring of 'symlink'

[Ludovic Courtès]

taylanbayirli@gmail.com (Taylan Ulrich "Bayırlı/Kammer") skribis:

> From 613c00221bf4e2bd5e809aebd792ed7c056455b3 Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Taylan=20Ulrich=20Bay=C4=B1rl=C4=B1/Kammer?=
>  <taylanbayirli@gmail.com>
> Date: Fri, 20 Feb 2015 21:11:03 +0100
> Subject: [PATCH] Correct docstring of 'symlink'
>
> * libguile/filesys.c (symlink): Correct the docstring, which had
>   'oldpath' and 'newpath' confused.

OK!  Could you also update the texi file?

Thanks,
Ludo'.

Re: [PATCH] Correct docstring of 'symlink'

[Taylan Ulrich Bayırlı/Kammer]

ludo@gnu.org (Ludovic Courtès) writes:

> Could you also update the texi file?

In (info "(guile) File System") it was already correct.

Taylan

Re: [PATCH] Correct docstring of 'symlink'

[Ludovic Courtès]

taylanbayirli@gmail.com (Taylan Ulrich "Bayırlı/Kammer") skribis:

> ludo@gnu.org (Ludovic Courtès) writes:
>
>> Could you also update the texi file?
>
> In (info "(guile) File System") it was already correct.

OK, please push then.

Thank you,
Ludo’.

Re: [PATCH] Correct docstring of 'symlink'

[Taylan Ulrich Bayırlı/Kammer]

ludo@gnu.org (Ludovic Courtès) writes:

> OK, please push then.

I don't have push access on Guile. :-)

Taylan

Re: [PATCH] Correct docstring of 'symlink'

[Ludovic Courtès]

taylanbayirli@gmail.com (Taylan Ulrich "Bayırlı/Kammer") skribis:

> ludo@gnu.org (Ludovic Courtès) writes:
>
>> OK, please push then.
>
> I don't have push access on Guile. :-)

Oops, pushed, thanks!

Ludo’.

Re: [PATCH] Correct docstring of 'symlink'

[Stefan Monnier]

> -	    "Create a symbolic link named @var{oldpath} with the value\n"
> -	    "(i.e., pointing to) @var{newpath}.  The return value is\n"
> +	    "Create a symbolic link named @var{newpath} with the value\n"
> +	    "(i.e., pointing to) @var{oldpath}.  The return value is\n"

This is weird terminology.

First the "new vs old" is meaningless for a symlink since the target may
not even exist.  In "man ln" the terminology used is "link-name vs
target" which I think is a lot more clear (Elisp's `make-symbolic-link'
uses "filename vs linkname" which is not as good).

Second, the GNU coding standards says:

   Please do not use the term "pathname" that is used in Unix
   documentation; use "file name" (two words) instead.  We use the term
   "path" only for search paths, which are lists of directory names.

so none of the two args should be named "<something>path".


        Stefan

Re: [PATCH] Correct docstring of 'symlink'

[Ludovic Courtès]

Stefan Monnier <monnier@iro.umontreal.ca> skribis:

>> -	    "Create a symbolic link named @var{oldpath} with the value\n"
>> -	    "(i.e., pointing to) @var{newpath}.  The return value is\n"
>> +	    "Create a symbolic link named @var{newpath} with the value\n"
>> +	    "(i.e., pointing to) @var{oldpath}.  The return value is\n"
>
> This is weird terminology.
>
> First the "new vs old" is meaningless for a symlink since the target may
> not even exist.  In "man ln" the terminology used is "link-name vs
> target" which I think is a lot more clear (Elisp's `make-symbolic-link'
> uses "filename vs linkname" which is not as good).
>
> Second, the GNU coding standards says:
>
>    Please do not use the term "pathname" that is used in Unix
>    documentation; use "file name" (two words) instead.  We use the term
>    "path" only for search paths, which are lists of directory names.
>
> so none of the two args should be named "<something>path".

Agreed on both points.  Unfortunately Guile is an old piece of software
and there are issues like this.

I would gladly accept a patch that fixes documentation to always use
“file name.”

Thanks,
Ludo’.