Update documentation. Use the namespace name "personal", instead of "private".

@@ -33,3 +33,4 @@ m4
 mailutils*.tar.*
 mailutils*.tar.*
 pathdefs.h
 pathdefs.h
 stamp-h1
 stamp-h1
+tmp/

-GNU mailutils NEWS -- history of user-visible changes. 2017-01-16
+GNU mailutils NEWS -- history of user-visible changes. 2017-01-20
 Copyright (C) 2002-2017 Free Software Foundation, Inc.
 Copyright (C) 2002-2017 Free Software Foundation, Inc.
 See the end of file for copying conditions.
 See the end of file for copying conditions.
 
 
@@ -7,6 +7,52 @@ Please send mailutils bug reports to <bug-mailutils@gnu.org>.
 
 
 Version 3.1.91 (Git)
 Version 3.1.91 (Git)
 
 
+* configuration syntax
+
+Statements that allow for variable substitution also allow for command
+expansion.  Commands are invoked the same way as in shell:
+
+   $(command [args...])
+
+The following commands are defined:
+
+ - localpart X
+     Treats X as an email address and returns its part preceding
+     the @-sign.  If there is no @-sign, returns X unchanged.
+
+ - domainpart X
+     Treats X as an email address and returns the part following
+     the @-sign.  If there is no @-sign, returns empty string.
+
+ - shell CMD [ARGS...]
+     Runs the shell command CMD with the given arguments.  Returns
+     the standard output from the command.  The command is invoked
+     using "/bin/sh -c" and can contain any valid shell construct.
+
+* imap4d
+
+Namespace configuration completely rewritten.  The "namespace" block
+statement defines a particular namespaces.  Within it, one or more
+"prefix" statements define prefixes available in that namespace, along
+with their mappings to the server filesystem, hierarchy delimiters etc.
+
+An example of namespace configuration:
+
+     namespace personal {
+        prefix "" {
+           directory "$home/mailfolder";
+        }
+        prefix "#MH:" {
+           directory "$home/Mail";
+           delimiter "/";
+           mailbox-type "mh";
+        }
+     }
+
+The following configuration statements have been withdrawn: homedir,
+personal-namespace, other-namespace, shared-namespace,
+other-mailbox-mode, shared-mailbox-mode.
+
 * mail
 * mail
 
 
 ** Modifying attachment name and filename
 ** Modifying attachment name and filename
@@ -24,7 +70,7 @@ description), and file name:
 
 
 Both options affect only the next `--attach' or `--attach-fd' option.
 Both options affect only the next `--attach' or `--attach-fd' option.
 
 
-** Constructing attachments from command line
+** Constructing attachments from the command line
 
 
 The new option `--attach-fd=N' instructs mail to read attachment from
 The new option `--attach-fd=N' instructs mail to read attachment from
 file descriptor N.  By default, the attachments created using this
 file descriptor N.  By default, the attachments created using this

@@ -830,6 +830,37 @@ value of @var{variable} is substituted.
 substituted, otherwise the expansion of @var{word} is substituted.
 substituted, otherwise the expansion of @var{word} is substituted.
 @end table
 @end table
 
 
+When a value is subject to variable expansion, it is also subject to
+@dfn{command expansion}.  Commands are invoked in string values using
+the following format:
+
+@example
+$(@var{cmd} @var{arg})
+@end example
+
+@noindent
+where @var{cmd} is the command name, and @var{args} is a list of
+arguments separated by whitespace.  Arguments can in turn contain
+variable and command references.
+
+The following commands are defined:
+
+@deffn {Command} localpart @var{string}
+Treats @var{string} as an email address and returns the part preceding
+the @samp{@@} sign.  If there is no @samp{@@} sign, returns @var{string}.
+@end deffn
+
+@deffn {Command} domainpart @var{string}
+Treats @var{string} as an email address and returns the part following
+the @samp{@@} sign.  If there is no @samp{@@} sign, returns empty string.
+@end deffn
+
+@deffn {Command} shell @var{cmd} @var{args}
+Runs the shell command @var{cmd} with the given arguments.  Returns
+the standard output from the command.  The command is invoked
+using @command{/bin/sh -c} and can contain any valid shell constructs.
+@end deffn
+
 The subsections below define variable names that are valid for use in
 The subsections below define variable names that are valid for use in
 each configuration statement.
 each configuration statement.
 
 
@@ -1168,6 +1199,7 @@ time, using the @samp{_PATH_MAILDIR} define from the include file
 @end enumerate
 @end enumerate
 
 
 @deffn {Configuration} mailbox-type @var{type}
 @deffn {Configuration} mailbox-type @var{type}
+@anchor{mailbox-type}
 @vrindex MU_DEFAULT_SCHEME
 @vrindex MU_DEFAULT_SCHEME
 Specifies the type of mailboxes.  By default, @samp{mbox} (UNIX mailbox)
 Specifies the type of mailboxes.  By default, @samp{mbox} (UNIX mailbox)
 is assumed.  This can be changed while configuring the package by
 is assumed.  This can be changed while configuring the package by
@@ -7559,16 +7591,30 @@ be run either as a standalone program or from @file{inetd.conf} file.
 @cindex IMAP4 namespace
 @cindex IMAP4 namespace
 
 
 GNU @command{imap4d} supports a notion of @dfn{namespaces} defined
 GNU @command{imap4d} supports a notion of @dfn{namespaces} defined
-in RFC 2342.  A namespace is a set of directories upon which the user
-has certain permissions.  It should be understood that these permissions
-apply only if the underlying filesystem allows them.
+in RFC 2342.  A namespace can be regarded as a list of triplets,
+defining locations to which the user has certain access rights.  Each
+triplet defines the @dfn{prefix}, under which the mailboxes can be
+found, @dfn{hierarchy delimiter}, a character used to delimit parts of
+a path to a mailbox, and a @dfn{directory} on the file system on the
+server, which actually holds the mailboxes.  Among these three values,
+only first two are visible to the client using the IMAP
+@samp{NAMESPACE} command.
 
 
-The three namespaces supported by @command{imap4d} are:
+There are three namespaces:
 
 
 @table @asis
 @table @asis
 @item Personal Namespace
 @item Personal Namespace
 A namespace that is within the personal scope of the authenticated user
 A namespace that is within the personal scope of the authenticated user
-on a particular connection.  The user has all permissions on this namespace.
+on a particular connection.  The user has all permissions on this
+namespace.
+
+By default, this namespace contains a single prefix:
+
+@example
+prefix: ""
+delimiter: /
+directory: home directory of the user
+@end example
 
 
 @item Other Users' Namespace
 @item Other Users' Namespace
 A namespace that consists of mailboxes from the ``Personal Namespaces''
 A namespace that consists of mailboxes from the ``Personal Namespaces''
@@ -7577,63 +7623,43 @@ namespace.  However, he is not allowed to use @samp{%} and @samp{*}
 wildcards with @command{LIST} command, that is he can access a
 wildcards with @command{LIST} command, that is he can access a
 mailbox only if he knows exactly its location.
 mailbox only if he knows exactly its location.
 
 
+By default, this namespace is empty.
+
 @item Shared Namespace
 @item Shared Namespace
 A namespace that consists of mailboxes that are intended to be shared
 A namespace that consists of mailboxes that are intended to be shared
 amongst users and do not exist within a user's Personal Namespace.
 amongst users and do not exist within a user's Personal Namespace.
 The user has all permissions on this namespace.
 The user has all permissions on this namespace.
-@end table
-
-@noindent
-By default, @command{imap4d} starts with the following namespaces:
 
 
-@table @asis
-@item Personal Namespace
-The home directory of the user, if exists.
-
-@item Other Users' Namespace
-Empty
-
-@item Shared Namespace
-Empty
+By default, this namespace is empty.
 @end table
 @end table
 
 
-@emph{Note}, that this means that by default, a user won't be able to
+The default values ensure that each user is able to
 see or otherwise access mailboxes residing in the directories other than
 see or otherwise access mailboxes residing in the directories other than
 his own home.
 his own home.
 
 
-To change these defaults, use @code{shared-namespace} and
-@code{other-namespace} configuration statements:
-
-@table @command
-@item shared-namespace @var{list}
-Set shared namespace.
-
-@item other-namespace @var{list}
-Set other users' namespace.
-@end table
-
-For both statements, the argument is a list of directories that belong
-to this namespace, e.g.:
+These defaults can be changed using the @code{namespace} block
+statement:
 
 
 @example
 @example
-shared-namespace (/var/spool/mail,/var/mail);
+namespace @var{name} @{
+    mailbox-mode @var{mode};
+    prefix @var{pfx} @{
+      directory @var{path};
+      delimiter @var{chr};
+      mailbox-type @var{type};
+    @}
+@}
 @end example
 @end example
 
 
-If during the session the user creates a mailbox within either of
-these namespaces, the mode of the mailbox is determined by the
-following configuration statements:
-
-@table @command
-@item shared-mailbox-mode @var{mode}
-Set file mode for mailboxes created in shared namespace.
-
-@item other-mailbox-mode @var{mode}
-Set file mode for mailboxes created in other users' namespace.
-@end table
+The @var{name} argument to the @code{namespace} statement declares
+which namespace is being configured.  Allowed values are:
+@samp{personal}, @samp{other}, and @samp{shared}.
 
 
-In both cases, the argument, @var{mode} is a list of symbolic mode
-settings, similar to that used by @command{chmod}.  It is a list of
-comma-separated mode change commands.  Each command begins with a
+The @code{mailbox-mode} statement configures the file mode for the
+mailboxes created within that namespace (provided that the directory
+permissions allow the user to create mailboxes).  The @var{mode}
+argument is a comma-delimited list of symbolic mode settings, similar
+to that used by @command{chmod}.  Each setting begins with a
 letter @samp{g}, which means set mode bits for file group, or
 letter @samp{g}, which means set mode bits for file group, or
 @samp{o}, which means set mode bits for other users (note, that there
 @samp{o}, which means set mode bits for other users (note, that there
 is no @samp{u} specifier, since user ownership of his mailbox cannot
 is no @samp{u} specifier, since user ownership of his mailbox cannot
@@ -7645,7 +7671,79 @@ For example, the following statement sets read and write permissions
 for the group:
 for the group:
 
 
 @example
 @example
-shared-namespace-mode g=rw;
+mailbox-mode g=rw;
+@end example
+
+The @code{prefix} statement configures available prefixes and
+determines their mappings to the server's file system.  The @var{pfx}
+argument defines the prefix which will be visible to the IMAP client.
+
+The @code{directory} statement defines the directory in the file
+system to which @var{pfx} is mapped.  Its argument can contain
+references to the following variables(@pxref{Variables}):
+
+@table @asis
+@item user
+Login name of the user.
+
+@item home
+Home directory of the user.
+@end table
+
+Exactly one @code{directory} statement must be present in each
+@code{prefix} block.
+
+The @code{delimiter} statement defines the folder hierarchy delimiter
+for that prefix.  It is optional, the default value being @samp{"/"}.
+
+The @code{mailbox-type} statement declares the type of the mailboxes
+within that prefix.   If present, its argument must be a valid mailbox
+type (e.g. @samp{mailbox}, @samp{maildir}, or @samp{mh}).  The IMAP
+@code{LIST} command will display only mailboxes of that type.  The
+@code{CREATE} command will create mailboxes of that type.
+
+In the absence of the @code{mailbox-type} statement, the IMAP
+@code{LIST} command will display mailboxes of any type supported by
+Mailutils.  The type of newly-created mailboxes is then determined by
+the @code{mailbox-type} statement (@pxref{mailbox-type}).
+
+Any number of @code{prefix} blocks can be present.  
+
+Consider, for example, the following configuration:
+
+@example
+@group
+namespace personal @{
+   prefix "" @{
+      directory "$home/mailfolder";
+   @}   
+   prefix "#MH:" @{
+      directory "$home/Mail";
+      delimiter "/";
+      mailbox-type "mh";
+   @}
+@}
+@end group
+@end example
+
+It defines the personal namespace containing two prefixes.  The empty
+prefix is mapped to the directory @file{mailfolder} in the home
+directory of the currently authenticated user.  Any type of mailboxes
+is supported within that prefix.
+
+The prefix @samp{#MH:} is mapped to the directory @file{Mail} in the
+home directory of the user, and is limited to contain only mailboxes
+in MH format.
+
+Note that if the prefixes @samp{""} is not defined in the personal
+namespace, the following default will be automatically created:
+
+@example
+@group
+prefix "" @{
+  directory "$home";
+@}
+@end group
 @end example
 @end example
 
 
 @node Conf-imap4d
 @node Conf-imap4d
@@ -7672,24 +7770,53 @@ configuration statements:
 @item tcp-wrappers  @tab @xref{tcp-wrappers statement}.
 @item tcp-wrappers  @tab @xref{tcp-wrappers statement}.
 @end multitable
 @end multitable
 
 
-@deffn {Imap4d Conf} shared-namespace @var{list}
-Set shared namespace.  @var{List} is a list of
-strings.  @xref{Namespace}, for a detailed description.
+@deffn {Imap4d Conf} namespace @var{name} @{ ... @}
+Configures namespace.  The argument is one of: @samp{personal},
+@samp{other}, @samp{shared}.  The following statements (described
+below) are allowed within curly braces: @code{mailbox-mode} and
+@code{prefix}.
+
+@xref{Namespace}.
+@end deffn
+
+@deffn {Imap4d namespace} mailbox-mode @var{mode}
+Configures the file mode for the mailboxes created within that
+namespace.  The syntax for @var{mode} is:
+
+@example
+g(+|=)[wr]+,o(+|=)[wr]+
+@end example
+
+@xref{Namespace,mailbox-mode}.
+@end deffn
+
+@deffn {Imap4d namespace} prefix @var{pfx} @{ ... @}
+Configures a prefix and determines its mapping to the server's file
+system.  The @var{pfx} argument is the prefix which will be
+visible to the IMAP client.  Available sub-statements are:
+@code{directory}, @code{delimiter}, and @code{mailbox-type}.
+
+@xref{Namespace,prefix}.
 @end deffn
 @end deffn
 
 
-@deffn {Imap4d Conf} other-namespace @var{list}
-Set other users' namespace.  @var{List} is a list of
-strings.  @xref{Namespace}, for a detailed description.
+@deffn {Imap4d namespace.prefix} directory @var{path}
+Defines the directory in the file system to which the prefix is
+mapped.
+
+@xref{Namespace,directory}.
 @end deffn
 @end deffn
 
 
-@deffn {Imap4d Conf} shared-mailbox-mode @var{str}
-Set file mode for mailboxes created within shared namespace.
-@xref{Namespace}, for a detailed description.
+@deffn {Imap4d namespace.prefix} delimiter @var{chr}
+Defines the folder hierarchy delimiter for the prefix.  Argument must
+be a single character.
+
+@xref{Namespace,delimiter}.
 @end deffn
 @end deffn
 
 
-@deffn {Imap4d Conf} other-mailbox-mode @var{str}
-Set file mode for mailboxes created within other users' namespace.
-@xref{Namespace}, for a detailed description.
+@deffn {Imap4d namespace.prefix} mailbox-type @var{type}
+Defines the type of the mailboxes inside that prefix.
+
+@xref{Namespace,mailbox-type}.
 @end deffn
 @end deffn
 
 
 @deffn {Imap4d Conf} login-disabled @var{bool}
 @deffn {Imap4d Conf} login-disabled @var{bool}
@@ -7708,11 +7835,6 @@ The default value for @var{mode} is @samp{700} (@samp{drwx------} in
 @code{ls} terms).  
 @code{ls} terms).  
 @end deffn
 @end deffn
 
 
-@deffn {Imap4d Conf} tls-required @var{bool}
-Require successful @code{STARTTLS} command before entering
-authentication phase.
-@end deffn
-
 @deffn {Imap4d Conf} preauth @var{mode}
 @deffn {Imap4d Conf} preauth @var{mode}
 Configure PREAUTH mode.  Valid arguments are:
 Configure PREAUTH mode.  Valid arguments are:
 
 

@@ -419,10 +419,12 @@ static struct mu_cfg_param prefix_param[] = {
     N_("Directory in the file system") },
     N_("Directory in the file system") },
   { "delimiter", mu_cfg_callback,
   { "delimiter", mu_cfg_callback,
     NULL, mu_offsetof (struct namespace_prefix, delim), cb_prefix_delim,
     NULL, mu_offsetof (struct namespace_prefix, delim), cb_prefix_delim,
-    N_("Hierarchy delimiter character") },
+    N_("Hierarchy delimiter character"),
+    N_("arg: character") },
   { "mailbox-type", mu_cfg_callback,
   { "mailbox-type", mu_cfg_callback,
     NULL, 0, cb_prefix_scheme,
     NULL, 0, cb_prefix_scheme,
-    N_("Type of mailboxes residing under this prefix") },
+    N_("Type of mailboxes residing under this prefix"),
+    N_("type: string") },
   { NULL }
   { NULL }
 };
 };
 
 
@@ -524,7 +526,7 @@ namespace_cfg_init (void)
   if (mu_create_canned_section ("namespace", &section))
   if (mu_create_canned_section ("namespace", &section))
     abort ();
     abort ();
   section->docstring = N_("Define a namespace");
   section->docstring = N_("Define a namespace");
-  section->label = "private | other | shared";
+  section->label = "personal | other | shared";
   section->parser = namespace_section_parser;
   section->parser = namespace_section_parser;
   mu_cfg_section_add_params (section, namespace_param);
   mu_cfg_section_add_params (section, namespace_param);
 }
 }
@@ -556,29 +558,6 @@ static struct mu_cfg_param imap4d_cfg_param[] = {
   
   
   { "namespace", mu_cfg_section },
   { "namespace", mu_cfg_section },
   
   
-#if 0
-  { "homedir", mu_c_string, &modify_homedir, 0, NULL,
-    N_("Modify home directory.") },
-
-  { "personal-namespace", MU_CFG_LIST_OF(mu_c_string), &namespace[NS_PRIVATE],
-    0, NULL, 
-    N_("Set personal namespace.") },
-  { "other-namespace", MU_CFG_LIST_OF(mu_c_string), &namespace[NS_OTHER],
-    0, NULL, 
-    N_("Set other users' namespace.") },
-  { "shared-namespace", MU_CFG_LIST_OF(mu_c_string), &namespace[NS_SHARED],
-    0, NULL,
-    N_("Set shared namespace.") },
-  FIXME
-  { "other-mailbox-mode", mu_cfg_callback, &mailbox_mode[NS_OTHER], 0,
-    cb_mailbox_mode,
-    N_("File mode for mailboxes in other namespace."),
-    N_("mode: g(+|=)[wr]+,o(+|=)[wr]+") },
-  { "shared-mailbox-mode", mu_cfg_callback, &mailbox_mode[NS_SHARED], 0,
-    cb_mailbox_mode,
-    N_("File mode for mailboxes in shared namespace."),
-    N_("mode: g(+|=)[wr]+,o(+|=)[wr]+") },
-#endif
   { "login-disabled", mu_c_bool, &login_disabled, 0, NULL,
   { "login-disabled", mu_c_bool, &login_disabled, 0, NULL,
     N_("Disable LOGIN command.") },
     N_("Disable LOGIN command.") },
   { "create-home-dir", mu_c_bool, &create_home_dir, 0, NULL,
   { "create-home-dir", mu_c_bool, &create_home_dir, 0, NULL,

@@ -161,7 +161,7 @@ struct imap4d_command
 #define ERR_STREAM_CREATE     9
 #define ERR_STREAM_CREATE     9
 
 
 /* Namespace numbers */
 /* Namespace numbers */
-#define NS_PRIVATE 0
+#define NS_PERSONAL 0
 #define NS_OTHER   1
 #define NS_OTHER   1
 #define NS_SHARED  2
 #define NS_SHARED  2
 #define NS_MAX     3
 #define NS_MAX     3

@@ -19,9 +19,9 @@
 #include <mailutils/assoc.h>
 #include <mailutils/assoc.h>
 
 
 struct namespace namespace[NS_MAX] = {
 struct namespace namespace[NS_MAX] = {
-  [NS_PRIVATE] = { "private" },
-  [NS_OTHER]   = { "other" },
-  [NS_SHARED]  = { "shared" }
+  [NS_PERSONAL] = { "personal" },
+  [NS_OTHER]    = { "other" },
+  [NS_SHARED]   = { "shared" }
 };
 };
   
   
 static mu_assoc_t prefixes;
 static mu_assoc_t prefixes;
@@ -124,7 +124,7 @@ namespace_init (void)
   pfx = mu_assoc_get (prefixes, "");
   pfx = mu_assoc_get (prefixes, "");
   if (pfx)
   if (pfx)
     {
     {
-      if (pfx->ns != NS_PRIVATE)
+      if (pfx->ns != NS_PERSONAL)
 	{
 	{
 	  mu_error (_("empty prefix not allowed in the namespace %s"),
 	  mu_error (_("empty prefix not allowed in the namespace %s"),
 		    namespace[pfx->ns].name);
 		    namespace[pfx->ns].name);
@@ -139,7 +139,7 @@ namespace_init (void)
       pfx->prefix = mu_strdup ("");
       pfx->prefix = mu_strdup ("");
       pfx->dir = mu_strdup ("$home");
       pfx->dir = mu_strdup ("$home");
       pfx->delim = '/';
       pfx->delim = '/';
-      priv = namespace_lookup ("private");
+      priv = namespace_lookup ("personal");
       mu_list_prepend (priv->prefixes, pfx);
       mu_list_prepend (priv->prefixes, pfx);
       rc = mu_assoc_install (prefixes, pfx->prefix, pfx);
       rc = mu_assoc_install (prefixes, pfx->prefix, pfx);
       if (rc)
       if (rc)
@@ -167,7 +167,7 @@ prefix_translate_name (struct namespace_prefix const *pfx, char const *name,
 	url = 0;
 	url = 0;
       name += pfxlen;
       name += pfxlen;
 
 
-      if (pfx->ns == NS_PRIVATE && strcmp (name, "INBOX") == 0)
+      if (pfx->ns == NS_PERSONAL && strcmp (name, "INBOX") == 0)
 	{
 	{
 	  tmpl = mu_strdup (auth_data->mailbox);
 	  tmpl = mu_strdup (auth_data->mailbox);
 	  return tmpl;//FIXME
 	  return tmpl;//FIXME
@@ -299,7 +299,7 @@ namespace_translate_name (char const *name, int url,
       
       
       switch (pfx->ns)
       switch (pfx->ns)
 	{
 	{
-	case NS_PRIVATE:
+	case NS_PERSONAL:
 	  mu_assoc_install (assoc, "user", auth_data->name);
 	  mu_assoc_install (assoc, "user", auth_data->name);
 	  mu_assoc_install (assoc, "home", real_homedir);
 	  mu_assoc_install (assoc, "home", real_homedir);
 	  break;
 	  break;
@@ -423,7 +423,7 @@ imap4d_namespace (struct imap4d_session *session,
 
 
   io_sendf ("* NAMESPACE ");
   io_sendf ("* NAMESPACE ");
 
 
-  print_namespace (NS_PRIVATE);
+  print_namespace (NS_PERSONAL);
   io_sendf (" ");
   io_sendf (" ");
   print_namespace (NS_OTHER);
   print_namespace (NS_OTHER);
   io_sendf (" ");
   io_sendf (" ");

@@ -18,7 +18,7 @@ gsasl {
 	enable off;
 	enable off;
 }
 }
 
 
-namespace private {
+namespace personal {
 	prefix "" {
 	prefix "" {
 		directory "$HOMEDIR";
 		directory "$HOMEDIR";
 	}
 	}