diff --git a/ChangeLog b/ChangeLog
index 1da0023a..b7fb2c95 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2009-01-19  Nicolas François  <nicolas.francois@centraliens.net>
+
+	* man/login.defs.d/UMASK.xml: Indicate how UMASK is used and
+	limitations.
+
 2009-01-06  Sebastian Rick Rijkers  <srrijkers@gmail.com>
 
 	* NEWS, src/su.c: Preserve COLORTERM in addition to TERM when su
diff --git a/man/login.defs.d/UMASK.xml b/man/login.defs.d/UMASK.xml
index 99352161..7cd3ea45 100644
--- a/man/login.defs.d/UMASK.xml
+++ b/man/login.defs.d/UMASK.xml
@@ -1,7 +1,7 @@
 <!--
    Copyright (c) 1991 - 1993, Julianne Frances Haugh
    Copyright (c) 1991 - 1993, Chip Rosenthal
-   Copyright (c) 2007 - 2008, Nicolas François
+   Copyright (c) 2007 - 2009, Nicolas François
    All rights reserved.
   
    Redistribution and use in source and binary forms, with or without
@@ -32,8 +32,20 @@
   <term><option>UMASK</option> (number)</term>
   <listitem>
     <para>
-      The permission mask is initialized to this value. If not specified,
-      the permission mask will be initialized to 022.
+      The file mode creation mask is initialized to this value. If not
+      specified, the mask will be initialized to 022.
+    </para>
+    <para>
+      <command>useradd</command> and <command>newusers</command> use this
+      mask to set the mode of the home directory they create
+    </para>
+    <para condition="no_pam">
+      It is also used by <command>login</command> to define users' initial
+      umask.  Note that this mask can be overriden by the user's GECOS
+      line (if <option>QUOTAS_ENAB</option> is set) or by the
+      specification of a limit with the <emphasis>K</emphasis> identifier
+      in <citerefentry><refentrytitle>limits</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>.
     </para>
   </listitem>
 </varlistentry>