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

[Fabrice Bauzac <libnoon at gmail dot com>]

Hello,

I have created Bugzilla 16073 for tracking this patch.

Thanks!

Best regards
Fabrice

2013/10/13 Fabrice Bauzac <libnoon@gmail.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