bug [ 1193849 ] os.path.expanduser documentation wrt. empty $HOME

Doc/lib/libposixpath.tex

@@ -55,12 +55,20 @@ Equivalent to \function{exists()} on platforms lacking
 \end{funcdesc}
 
 \begin{funcdesc}{expanduser}{path}
-Return the argument with an initial component of \samp{\~} or
+On \UNIX, return the argument with an initial component of \samp{\~} or
-\samp{\~\var{user}} replaced by that \var{user}'s home directory.  An
+\samp{\~\var{user}} replaced by that \var{user}'s home directory.
-initial \samp{\~{}} is replaced by the environment variable
+An initial \samp{\~} is replaced by the environment variable
-\envvar{HOME}; an initial \samp{\~\var{user}} is looked up in the
+\envvar{HOME} if it is set; otherwise the current user's home directory
-password directory through the built-in module
+is looked up in the password directory through the built-in module
-\refmodule{pwd}\refbimodindex{pwd}.  If the expansion fails, or if the
+\refmodule{pwd}\refbimodindex{pwd}.
+An initial \samp{\~\var{user}} is looked up directly in the
+password directory.
+
+On Windows, only \samp{\~} is supported; it is replaced by the
+environment variable \envvar{HOME} or by a combination of
+\envvar{HOMEDRIVE} and \envvar{HOMEPATH}.
+
+If the expansion fails or if the
 path does not begin with a tilde, the path is returned unchanged.
 \end{funcdesc}
 
@@ -158,7 +166,7 @@ slashes.
 
 \begin{funcdesc}{normpath}{path}
 Normalize a pathname.  This collapses redundant separators and
-up-level references, e.g. \code{A//B}, \code{A/./B} and
+up-level references so that \code{A//B}, \code{A/./B} and
 \code{A/foo/../B} all become \code{A/B}.  It does not normalize the
 case (use \function{normcase()} for that).  On Windows, it converts
 forward slashes to backward slashes. It should be understood that this may
@@ -234,7 +242,7 @@ is a directory).  The argument \var{dirname} specifies the visited
 directory, the argument \var{names} lists the files in the directory
 (gotten from \code{os.listdir(\var{dirname})}).
 The \var{visit} function may modify \var{names} to
-influence the set of directories visited below \var{dirname}, e.g., to
+influence the set of directories visited below \var{dirname}, e.g. to
 avoid visiting certain parts of the tree.  (The object referred to by
 \var{names} must be modified in place, using \keyword{del} or slice
 assignment.)

Misc/NEWS

@@ -456,6 +456,8 @@ Tests
 Documentation
 -------------
 
+- Bug #1193849: Clarify os.path.expanduser() documentation.
+
 - Bug #1243192: re.UNICODE and re.LOCALE affect \d, \D, \s and \S.
 
 - Bug #755617: Document the effects of os.chown() on Windows.