manual: Improve documentation of get_current_dir_name. [BZ #6889]

  This is a minor rewording to clarify the behaviour of
get_current_dir_name.  Additionally, the @vindex is moved above the
@deftypefun so that following links give a better result with regard
to context.

	[BZ #6889]
	* manual/filesys.texi (get_current_dir_name): Clarify
	behaviour.
---
 manual/filesys.texi | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)
  

On 02/16/2018 08:47 AM, Rical Jasan wrote:
> This is a minor rewording to clarify the behaviour of
> get_current_dir_name.  Additionally, the @vindex is moved above the
> @deftypefun so that following links give a better result with regard
> to context.
> 
> 	[BZ #6889]
> 	* manual/filesys.texi (get_current_dir_name): Clarify
> 	behaviour.

OK.

I can't express how much I appreciate having someone tidy up the manual
in this way. Thank you.

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

> ---
>  manual/filesys.texi | 17 +++++++++--------
>  1 file changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index ca77996902..cc70a6b7ee 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -147,19 +147,20 @@ necessarily enough space to contain the directory name.  That is why
>  this function is deprecated.
>  @end deftypefn
>  
> +@vindex PWD
>  @deftypefun {char *} get_current_dir_name (void)
>  @standards{GNU, unistd.h}
>  @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
>  @c Besides getcwd, which this function calls as a fallback, it calls
>  @c getenv, with the potential thread-safety issues that brings about.
> -@vindex PWD
> -This @code{get_current_dir_name} function is basically equivalent to
> -@w{@code{getcwd (NULL, 0)}}.  The only difference is that the value of
> -the @code{PWD} variable is returned if this value is correct.  This is a
> -subtle difference which is visible if the path described by the
> -@code{PWD} value is using one or more symbol links in which case the
> -value returned by @code{getcwd} can resolve the symbol links and
> -therefore yield a different result.
> +The @code{get_current_dir_name} function is basically equivalent to
> +@w{@code{getcwd (NULL, 0)}}, except the value of the @env{PWD}
> +environment variable is first examined, and if it does in fact
> +correspond to the current directory, that value is returned.  This is
> +a subtle difference which is visible if the path described by the
> +value in @env{PWD} is using one or more symbolic links, in which case
> +the value returned by @code{getcwd} would resolve the symbolic links
> +and therefore yield a different result.
>  
>  This function is a GNU extension.
>  @end deftypefun
>
  

On 02/16/2018 09:10 AM, Carlos O'Donell wrote:
> On 02/16/2018 08:47 AM, Rical Jasan wrote:
>> This is a minor rewording to clarify the behaviour of
>> get_current_dir_name.  Additionally, the @vindex is moved above the
>> @deftypefun so that following links give a better result with regard
>> to context.
>>
>> 	[BZ #6889]
>> 	* manual/filesys.texi (get_current_dir_name): Clarify
>> 	behaviour.
> OK.

Committed: 7d15ef84f50a

> I can't express how much I appreciate having someone tidy up the manual
> in this way. Thank you.

It's low-hanging fruit, but also a ten-year-old bug.  I was just happy
to see this one and think, "I can squash that."  :)

Thank you,
Rical