Re: [PATCH] Improve the manual on symbolic links.

[Fabrice Bauzac <libnoon at gmail dot com>]

Hello,

2013/10/13 OndÅej BÃlka <neleai@seznam.cz>:
> A better naming would be welcome, I would be for naming them target and
> link_name as "man ln" does.
>
> You need an changelog entry which describes changed files in following
> format.
>
>         * manual/filesys.texi: Describe your change.

Done!  Could you please review the updated patch?

---
 ChangeLog           |  6 ++++++
 manual/filesys.texi | 21 ++++++++++++++-------
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 2c32f27..f8a6ea4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2013-10-13  Fabrice Bauzac  <libnoon@gmail.com>
+
+ * manual/filesys.texi (Symbolic Links): Fix typos, add
+ explanations on symbolic links, improve the documentation of
+ symlink().
+
 2013-10-12  Joseph Myers  <joseph@codesourcery.com>

  * soft-fp/double.h: Indent preprocessor directives inside #if.
diff --git a/manual/filesys.texi b/manual/filesys.texi
index 1cac453..4155cd8 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -1163,9 +1163,15 @@ purpose is to obtain information about the
link.  @code{link}, the
 function that makes a hard link, does too.  It makes a hard link to the
 symbolic link, which one rarely wants.

-Some systems have for some functions operating on files have a limit on
+The content of a symbolic link is a mere string; this string is
+intended to depict the absolute or relative path of the target of the
+link.  Relative paths are relative to the symbolic link's location: if
+a relative symbolic link is moved while its target is not, the link
+will most probably not point to the target anymore.
+
+Some systems have, for some functions operating on files, a limit on
 how many symbolic links are followed when resolving a path name.  The
-limit if it exists is published in the @file{sys/param.h} header file.
+limit, if it exists, is published in the @file{sys/param.h} header file.

 @comment sys/param.h
 @comment BSD
@@ -1185,9 +1191,10 @@ Prototypes for most of the functions listed in
this section are in

 @comment unistd.h
 @comment BSD
-@deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
-The @code{symlink} function makes a symbolic link to @var{oldname} named
-@var{newname}.
+@deftypefun int symlink (const char *@var{target}, const char *@var{linkname})
+The @code{symlink} function makes a symbolic link named @var{linkname}
+whose content is @var{target}, which is usually a relative or absolute
+path of another file.

 The normal return value from @code{symlink} is @code{0}.  A return value
 of @code{-1} indicates an error.  In addition to the usual file name
@@ -1196,10 +1203,10 @@ error conditions are defined for this function:

 @table @code
 @item EEXIST
-There is already an existing file named @var{newname}.
+There is already an existing file named @var{linkname}.

 @item EROFS
-The file @var{newname} would exist on a read-only file system.
+The file @var{linkname} would exist on a read-only file system.

 @item ENOSPC
 The directory or file system cannot be extended to make the new link.
-- 
1.8.1.2

Thanks!

Best regards
Fabrice

Attachment: 0001-Improve-the-manual-on-symbolic-links.patch
Description: Binary data