Expand docs re. logs dir, and make eximon logs dir match exim's. Bug 1324

[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 7527121819d3a74e530fc3aa46511fca415dccce..667857a996daf38f6d3a7c90919220ab0eda6013 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9031,6 +9031,30 @@ When compiling a function that is to be used in this way with gcc,
 you need to add &%-shared%& to the gcc command. Also, in the Exim build-time
 configuration, you must add &%-export-dynamic%& to EXTRALIBS.
 
+
+.vitem "&*${env{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&"
+.cindex "expansion" "extracting value from environment"
+.cindex "environment" "value from"
+The key is first expanded separately, and leading and trailing white space
+removed.
+This is then searched for as a name in the environment.
+If a variable is found then its value is placed in &$value$&
+and <&'string1'&> is expanded, otherwise <&'string2'&> is expanded.
+
+Instead of {<&'string2'&>} the word &"fail"& (not in curly brackets) can
+appear, for example:
+.code
+${env{USER}{$value} fail }
+.endd
+This forces an expansion failure (see section &<<SECTforexpfai>>&);
+{<&'string1'&>} must be present for &"fail"& to be recognized.
+
+If {<&'string2'&>} is omitted an empty string is substituted on 
+search failure.
+If {<&'string1'&>} is omitted the search result is substituted on
+search success.
+
+
 .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
        {*&<&'string3'&>&*}}*&"
 .cindex "expansion" "extracting substrings by key"
@@ -14929,8 +14953,9 @@ section &<<SECTmessiden>>&.
 This option sets the path which is used to determine the names of Exim's log
 files, or indicates that logging is to be to syslog, or both. It is expanded
 when Exim is entered, so it can, for example, contain a reference to the host
-name. If no specific path is set for the log files at compile or run time, they
-are written in a sub-directory called &_log_& in Exim's spool directory.
+name. If no specific path is set for the log files at compile or run time,
+or if the option is unset at run time (i.e.  &`log_file_path = `&)
+they are written in a sub-directory called &_log_& in Exim's spool directory.
 Chapter &<<CHAPlog>>& contains further details about Exim's logging, and
 section &<<SECTwhelogwri>>& describes how the contents of &%log_file_path%& are
 used. If this string is fixed at your installation (contains no expansion
@@ -34647,8 +34672,9 @@ equivalent to the setting:
 .code
 log_file_path = $spool_directory/log/%slog
 .endd
-If you do not specify anything at build time or run time, that is where the
-logs are written.
+If you do not specify anything at build time or run time,
+or if you unset the option at run time (i.e. &`log_file_path = `&),
+that is where the logs are written.
 
 A log file path may also contain &`%D`& or &`%M`& if datestamped log file names
 are in use &-- see section &<<SECTdatlogfil>>& below.