Merge branch 'siri/logger/post-21/OTP-15132' into maint

* siri/logger/post-21/OTP-15132:
  [logger] Allow setting kernel parameter 'logger_level' to 'all'
  [kernel] Reduce risk of dead lock when terminating logger_sup
  [logger] Fix regexp replacement for unicode strings
  Update proc_lib:report_cb to obey logger formatter's size limiting params
  [logger] Allow report callback with two arguments returning a string
  Don't call report_cb from cth_log_redirect - formatter does that
  Add legacy test of sasl_report_file_h and size limiting
  [logger] Remove compiler warnings in test
  [logger] Fix problem with test cases waiting for handler restart
  [logger] Add ?LOG macro which takes Level as argument
  [logger] Improve spec for set_handler_config/3 and set_primary_config/2
  [logger] Generate .png file from .dia
  [logger] Update documentation

7 files changed, 139 insertions, 56 deletions

diff --git a/lib/kernel/doc/src/.gitignore b/lib/kernel/doc/src/.gitignore
new file mode 100644
index 0000000000..c2813ac866
--- /dev/null
+++ b/lib/kernel/doc/src/.gitignore
@@ -0,0 +1 @@
+*.eps
\ No newline at end of file
diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile
index f34eee71ba..fceba14515 100644
--- a/lib/kernel/doc/src/Makefile
+++ b/lib/kernel/doc/src/Makefile
@@ -84,6 +84,7 @@ XML_CHAPTER_FILES = \
 
 BOOK_FILES = book.xml
 
+# The .png file is generated from a .dia file with target 'update_png'
 IMAGE_FILES = \
 	logger_arch.png
 
@@ -112,6 +113,17 @@ SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
 TOP_SPECS_FILE = specs.xml
 
 # ----------------------------------------------------
+# FIGURES
+# ----------------------------------------------------
+# In order to update the figures you have to have both dia
+# and imagemagick installed.
+# The generated .png file must be committed.
+
+update_png:
+	dia --export=logger_arch.eps logger_arch.dia
+	convert logger_arch.eps -resize 65% logger_arch.png
+
+# ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
 XML_FLAGS +=
@@ -147,7 +159,7 @@ clean clean_docs:
 	rm -f $(MAN6DIR)/*
 	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
 	rm -f $(SPECDIR)/*
-	rm -f errs core *~
+	rm -f errs core *~ *.eps
 
 $(SPECDIR)/specs_erl_prim_loader_stub.xml:
 	$(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 33f1919de0..f1830a8224 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -98,46 +98,6 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
 
   <datatypes>
     <datatype>
-      <name name="primary_config"/>
-      <desc>
-	<p>Primary configuration data for Logger. The following
-	  default values apply:</p>
-	<list>
-	  <item><c>level => info</c></item>
-	  <item><c>filter_default => log</c></item>
-	  <item><c>filters => []</c></item>
-	</list>
-      </desc>
-    </datatype>
-    <datatype>
-      <name name="handler_config"/>
-      <desc>
-	<p>Handler configuration data for Logger. The following
-	  default values apply:</p>
-	<list>
-	  <item><c>level => all</c></item>
-	  <item><c>filter_default => log</c></item>
-	  <item><c>filters => []</c></item>
-	  <item><c>formatter => {logger_formatter, DefaultFormatterConfig</c>}</item>
-	</list>
-	<p>In addition to these, the following fields are
-	  automatically inserted by Logger, values taken from the
-	  two first parameters
-	  to <seealso marker="#add_handler-3"><c>add_handler/3</c></seealso>:</p>
-	<list>
-	  <item><c>id => HandlerId</c></item>
-	  <item><c>module => Module</c></item>
-	</list>
-	<p>Handler specific configuration data is inserted by the
-	  handler callback itself, in a sub structure associated with
-	  the field named <c>config</c>.</p>
-	<p>See the <seealso marker="logger_formatter#type-config">
-	    <c>logger_formatter(3)</c></seealso> manual page for
-	  information about the default configuration for this
-	  formatter.</p>
-      </desc>
-    </datatype>
-    <datatype>
       <name name="filter"/>
       <desc>
 	<p>A filter which can be installed as a handler filter, or as
@@ -172,6 +132,39 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
       </desc>
     </datatype>
     <datatype>
+      <name name="handler_config"/>
+      <desc>
+	<p>Handler configuration data for Logger. The following
+	  default values apply:</p>
+	<list>
+	  <item><c>level => all</c></item>
+	  <item><c>filter_default => log</c></item>
+	  <item><c>filters => []</c></item>
+	  <item><c>formatter => {logger_formatter, DefaultFormatterConfig</c>}</item>
+	</list>
+	<p>In addition to these, the following fields are
+	  automatically inserted by Logger, values taken from the
+	  two first parameters
+	  to <seealso marker="#add_handler-3"><c>add_handler/3</c></seealso>:</p>
+	<list>
+	  <item><c>id => HandlerId</c></item>
+	  <item><c>module => Module</c></item>
+	</list>
+	<p>These are read-only and cannot be changed in runtime.</p>
+	<p>Handler specific configuration data is inserted by the
+	  handler callback itself, in a sub structure associated with
+	  the field named <c>config</c>. See
+	  the <seealso marker="logger_std_h"><c>logger_std_h(3)</c></seealso>
+	  and <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso>
+	  manual pages for information about the specifc configuration
+	  for these handlers.</p>
+	<p>See the <seealso marker="logger_formatter#type-config">
+	    <c>logger_formatter(3)</c></seealso> manual page for
+	  information about the default configuration for this
+	  formatter.</p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="handler_id"/>
       <desc>
 	<p>A unique identifier for a handler instance.</p>
@@ -234,7 +227,10 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
 	      a <seealso marker="#type-report"><c>report()</c></seealso>,
 	      the <c>report_cb</c> key can be associated with a fun
 	      (report callback) that converts the report to a format
-	      string and arguments. See
+	      string and arguments, or directly to a string. See the
+	      type definition
+	      of <seealso marker="#type-report_cb"><c>report_cb()</c></seealso>,
+	      and
 	      section <seealso marker="logger_chapter#log_message">Log
 	      Message</seealso> in the User's Guide for more
 	      information about report callbacks.</p>
@@ -249,12 +245,40 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
       </desc>
     </datatype>
     <datatype>
+      <name name="primary_config"/>
+      <desc>
+	<p>Primary configuration data for Logger. The following
+	  default values apply:</p>
+	<list>
+	  <item><c>level => info</c></item>
+	  <item><c>filter_default => log</c></item>
+	  <item><c>filters => []</c></item>
+	</list>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="report"/>
       <desc>
 	<p></p>
       </desc>
     </datatype>
     <datatype>
+      <name name="report_cb"/>
+      <desc>
+	<p>A fun which converts a <seealso marker="#type-report"><c>report()</c>
+	  </seealso> to a format string and arguments, or directly to a string.
+	  See section <seealso marker="logger_chapter#log_message">Log
+	    Message</seealso> in the User's Guide for more
+	  information.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="report_cb_config"/>
+      <desc>
+	<p></p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="timestamp"/>
       <desc>
 	<p>A timestamp produced
@@ -285,13 +309,16 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
       <item><c>?LOG_INFO(FunOrFormat,Args[,Metadata])</c></item>
       <item><c>?LOG_DEBUG(StringOrReport[,Metadata])</c></item>
       <item><c>?LOG_DEBUG(FunOrFormat,Args[,Metadata])</c></item>
+      <item><c>?LOG(Level,StringOrReport[,Metadata])</c></item>
+      <item><c>?LOG(Level,FunOrFormat,Args[,Metadata])</c></item>
     </list>
 
     <p>All macros expand to a call to Logger, where <c>Level</c> is
-      taken from the macro name, and location data is added to the
-      metadata. See the description of
+      taken from the macro name, or from the first argument in the
+      case of the <c>?LOG</c> macro. Location data is added to the
+      metadata as described under
       the <seealso marker="#type-metadata"><c>metadata()</c></seealso>
-      type for more information about the location data.</p>
+      type definition.</p>
 
     <p>The call is wrapped in a case statement and will be evaluated
       only if <c>Level</c> is equal to or below the configured log
@@ -690,15 +717,30 @@ start(_, []) ->
     </func>
 
     <func>
-      <name name="set_handler_config" arity="3"/>
+      <name name="set_handler_config" arity="3" clause_i="1"/>
+      <name name="set_handler_config" arity="3" clause_i="2"/>
+      <name name="set_handler_config" arity="3" clause_i="3"/>
+      <name name="set_handler_config" arity="3" clause_i="4"/>
+      <name name="set_handler_config" arity="3" clause_i="5"/>
       <fsummary>Add or update configuration data for the specified
         handler.</fsummary>
+      <type variable="HandlerId"/>
+      <type variable="Level" name_i="1"/>
+      <type variable="FilterDefault" name_i="2"/>
+      <type variable="Filters" name_i="3"/>
+      <type variable="Formatter" name_i="4"/>
+      <type variable="Config" name_i="5"/>
+      <type variable="Return"/>
       <desc>
         <p>Add or update configuration data for the specified
           handler. If the given <c><anno>Key</anno></c> already
           exists, its associated value will be changed
-          to <c><anno>Value</anno></c>. If it does not exist, it will
+          to the given value. If it does not exist, it will
           be added.</p>
+	<p>See the definition of
+	  the <seealso marker="#type-handler_config">
+	    <c>handler_config()</c></seealso> type for more
+	  information about the different parameters.</p>
       </desc>
     </func>
 
@@ -721,13 +763,18 @@ start(_, []) ->
     </func>
 
     <func>
-      <name name="set_primary_config" arity="2"/>
+      <name name="set_primary_config" arity="2" clause_i="1"/>
+      <name name="set_primary_config" arity="2" clause_i="2"/>
+      <name name="set_primary_config" arity="2" clause_i="3"/>
       <fsummary>Add or update primary configuration data for Logger.</fsummary>
+      <type variable="Level" name_i="1"/>
+      <type variable="FilterDefault" name_i="2"/>
+      <type variable="Filters" name_i="3"/>
       <desc>
         <p>Add or update primary configuration data for Logger. If the
           given <c><anno>Key</anno></c> already exists, its associated
-          value will be changed to <c><anno>Value</anno></c>. If it
-          does not exist, it will be added.</p>
+          value will be changed to the given value. If it does not
+          exist, it will be added.</p>
       </desc>
     </func>
 
diff --git a/lib/kernel/doc/src/logger_arch.dia b/lib/kernel/doc/src/logger_arch.dia
new file mode 100644
index 0000000000..97be31856e
--- /dev/null
+++ b/lib/kernel/doc/src/logger_arch.dia
diff --git a/lib/kernel/doc/src/logger_arch.png b/lib/kernel/doc/src/logger_arch.png
index a3a863c511..70933a5a41 100644
--- a/lib/kernel/doc/src/logger_arch.png
+++ b/lib/kernel/doc/src/logger_arch.png
diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index f4a752bde9..dc68d5c761 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -69,6 +69,8 @@
       figure shows two log handlers, but any number of handlers can be
       installed.</p>
 
+    <!-- The image is edited with dia in logger_arch.dia file,
+	 and .png file generated with make target 'png'. -->
     <image file="logger_arch.png">
       <icaption>Conceptual Overview</icaption>
     </image>
@@ -192,10 +194,26 @@
 	the log event's <seealso marker="#metadata">metadata</seealso>.
 	The report callback is a convenience function that
 	the <seealso marker="#formatters">formatter</seealso> can use
-	to convert the report to a format string and arguments. The
+	to convert the report to a format string and arguments, or
+	directly to a string. The
 	formatter can also use its own conversion function, if no
 	callback is provided, or if a customized formatting is
 	desired.</p>
+      <p>The report callback must be a fun with one or two
+	arguments. If it takes one argument, this is the report
+	itself, and the fun returns a format string and arguments:</p>
+      <pre>fun((<seealso marker="logger#type-report"><c>logger:report()</c></seealso>) -> {<seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso>,[term()]})</pre>
+      <p>If it takes two arguments, the first is the report, and the
+	second is a map containing extra data that allows direct
+	coversion to a string:</p>
+      <pre>fun((<seealso marker="logger#type-report"><c>logger:report()</c></seealso>,<seealso marker="logger#type-report_cb_config"><c>logger:report_cb_config()</c></seealso>) -> <seealso marker="stdlib:unicode#type-chardata"><c>unicode:chardata()</c></seealso>)
+      </pre>
+      <p>The fun must obey the <c>encoding</c>, <c>depth</c>
+	and <c>chars_limit</c> parameters provided in the second
+	argument, as the formatter can not do anything useful of these
+	parameters with the returned string. This variant is used when
+	the formatting of the report depends on the size and encoding
+	parameters.</p>
       <p>Example, format string and arguments:</p>
       <code>logger:error("The file does not exist: ~ts",[Filename])</code>
       <p>Example, string:</p>
diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml
index e777afaf86..9226d19834 100644
--- a/lib/kernel/doc/src/logger_formatter.xml
+++ b/lib/kernel/doc/src/logger_formatter.xml
@@ -78,10 +78,17 @@
 	      format controls ~p and ~w are replaced with ~P and ~W,
 	      respectively, and the value is used as the depth
 	      parameter. For details, see
-	      <seealso marker="stdlib:io#format-2">io:format/2,3</seealso>
+	      <seealso marker="stdlib:io#format-2"><c>io:format/2,3</c></seealso>
 	      in STDLIB.</p>
 	    <p>Defaults to <c>unlimited</c>.</p>
 	  </item>
+	  <tag><c>encoding = </c><seealso marker="stdlib:unicode#type-encoding">
+	      <c>unicode:encoding()</c></seealso></tag>
+	  <item>
+	    <p>This parameter must reflect the encoding of the device
+	      that the handler prints to.</p>
+	    <p>Defaults to <c>utf8</c></p>
+	  </item>
 	  <tag><c>legacy_header = boolean()</c></tag>
 	  <item>
 	    <p>If set to <c>true</c> a header field is added to
@@ -105,7 +112,8 @@
 	      by <c>chars_limit</c> or <c>depth</c>, it is truncated.</p>
 	    <p>Defaults to <c>unlimited</c>.</p>
 	  </item>
-	  <tag><c>report_cb = fun((</c><seealso marker="logger#type-report"><c>logger:report()</c></seealso><c>) -> {</c><seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso><c>, [term()]})</c></tag>
+	  <tag><c>report_cb = </c><seealso marker="logger#type-report_cb">
+	      <c>logger:report_cb()</c></seealso></tag>
 	  <item>
 	    <p>A report callback is used by the formatter to transform
 	      log messages on report form to a format string and
@@ -119,9 +127,6 @@
 	      both the default report callback, and any report
 	      callback found in metadata. That is, all reports are
 	      converted by this configured function.</p>
-	    <p>The value must be a function with arity 1,
-	      returning <c>{Format,Args}</c>, and it will be called
-	      with a report as only argument.</p>
 	  </item>
 	  <tag><c>single_line = boolean()</c></tag>
 	  <item>