[PATCH] Improve the manual on symbolic links.

[Fabrice Bauzac <libnoon at gmail dot com>]

Hello libc developers,

I would like to submit a humble contribution to the GNU libc manual.

Currently the manual documents the symlink() function as this:

Function: int symlink (const char *oldname, const char *newname)
The symlink function makes a symbolic link to oldname named newname. [...]

I find it impractical because, as I can never remember if the symlink
is the first or second argument, I have to think about OLDNAME and
NEWNAME to realize that NEWNAME is actually the symlink, while OLDNAME
the contents of the symlink.

It has been a long time since I thought it would be clearer if the
parameters were simply named CONTENTS and FILENAME.

I have made this change in the attached patch, along with a few
additions/corrections on filesys.texi.

Could you please review it?

Thanks!

Best regards
Fabrice

>From b617ef4664aae9971c2138659698e38c80a1c3ae Mon Sep 17 00:00:00 2001
From: Fabrice Bauzac <libnoon@gmail.com>
Date: Sat, 12 Oct 2013 20:43:46 +0200
Subject: [PATCH] Improve the manual on symbolic links.

---
 manual/filesys.texi | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/manual/filesys.texi b/manual/filesys.texi
index 1cac453..6da0ec6 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{value}, const char *@var{filename})
+The @code{symlink} function makes a symbolic link named @var{filename}
+whose content is @var{value}, 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{filename}.

 @item EROFS
-The file @var{newname} would exist on a read-only file system.
+The file @var{filename} 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

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