Merge branch 'xsipewe/dialyzer/doc_cleanup' into maint

* xsipewe/dialyzer/doc_cleanup:
  Update Dialyzer documentation

5 files changed, 643 insertions, 496 deletions

diff --git a/lib/dialyzer/doc/src/book.xml b/lib/dialyzer/doc/src/book.xml
index aecc0e5bfa..46df8b81b8 100644
--- a/lib/dialyzer/doc/src/book.xml
+++ b/lib/dialyzer/doc/src/book.xml
@@ -25,7 +25,7 @@
     <title>Dialyzer</title>
     <prepared></prepared>
     <docno></docno>
-    <date></date>
+    <date>2016-09-19</date>
     <rev></rev>
     <file>book.xml</file>
   </header>
diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml
index 619db125b1..553bfef41b 100644
--- a/lib/dialyzer/doc/src/dialyzer.xml
+++ b/lib/dialyzer/doc/src/dialyzer.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2006</year><year>2015</year>
+      <year>2006</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -25,341 +25,477 @@
     <title>dialyzer</title>
     <prepared></prepared>
     <docno></docno>
-    <date></date>
+    <date>2016-09-20</date>
     <rev></rev>
+    <file>dialyzer.xml</file>
   </header>
   <module>dialyzer</module>
-  <modulesummary>The Dialyzer, a DIscrepancy AnalYZer for ERlang programs</modulesummary>
+  <modulesummary>Dialyzer, a DIscrepancy AnaLYZer for ERlang programs.
+  </modulesummary>
   <description>
-    <p>The Dialyzer is a static analysis tool that identifies software
-    discrepancies such as definite type errors, code which has become
-    dead or unreachable due to some programming error, unnecessary
-    tests, etc. in single Erlang modules or entire (sets of)
-    applications. Dialyzer starts its analysis from either
-    debug-compiled BEAM bytecode or from Erlang source code. The file
-    and line number of a discrepancy is reported along with an
-    indication of what the discrepancy is about. Dialyzer bases its
-    analysis on the concept of success typings which allows for sound
-    warnings (no false positives).</p>
-    <p>Read more about Dialyzer and about how to use it from the GUI
-    in <seealso marker="dialyzer_chapter">Dialyzer User's
-    Guide</seealso>.</p>
+    <p>Dialyzer is a static analysis tool that identifies software
+      discrepancies, such as definite type errors, code that has become dead
+      or unreachable because of programming error, and unnecessary tests,
+      in single Erlang modules or entire (sets of) applications.</p>
+
+    <p>Dialyzer starts its analysis from either
+      debug-compiled BEAM bytecode or from Erlang source code. The file
+      and line number of a discrepancy is reported along with an
+      indication of what the discrepancy is about. Dialyzer bases its
+      analysis on the concept of success typings, which allows for sound
+      warnings (no false positives).</p>
   </description>
 
   <section>
-    <title>Using the Dialyzer from the command line</title>
-    <p>Dialyzer also has a command line version for automated use. Below is a
-      brief description of the list of its options. The same information can
-      be obtained by writing</p>
-    <code type="none">
-      dialyzer --help</code>
-    <p>in a shell. Please refer to the GUI description for more details on
-      the operation of Dialyzer.</p>
-    <p>The exit status of the command line version is:</p>
+    <marker id="command_line"></marker>
+    <title>Using Dialyzer from the Command Line</title>
+    <p>Dialyzer has a command-line version for automated use. This
+      section provides a brief description of the options. The same information
+      can be obtained by writing the following in a shell:</p>
+
     <code type="none">
-      0 - No problems were encountered during the analysis and no
-          warnings were emitted.
-      1 - Problems were encountered during the analysis.
-      2 - No problems were encountered, but warnings were emitted.</code>
-    <p>Usage:</p>
+dialyzer --help</code>
+
+    <p>For more details about the operation of Dialyzer, see section
+      <seealso marker="dialyzer_chapter#dialyzer_gui">
+      Using Dialyzer from the GUI</seealso> in the User's Guide.</p>
+
+    <p><em>Exit status of the command-line version:</em></p>
+
+    <taglist>
+      <tag><c>0</c></tag>
+      <item>
+        <p>No problems were found during the analysis and no warnings were
+          emitted.</p>
+      </item>
+      <tag><c>1</c></tag>
+      <item>
+        <p>Problems were found during the analysis.</p>
+      </item>
+      <tag><c>2</c></tag>
+      <item>
+        <p>No problems were found during the analysis, but warnings were
+          emitted.</p>
+      </item>
+    </taglist>
+
+    <p><em>Usage:</em></p>
+
     <code type="none">
-       dialyzer [--help] [--version] [--shell] [--quiet] [--verbose]
-		[-pa dir]* [--plt plt] [--plts plt*] [-Ddefine]*
-                [-I include_dir]* [--output_plt file] [-Wwarn]* [--raw]
-                [--src] [--gui] [files_or_dirs] [-r dirs]
-                [--apps applications] [-o outfile]
-		[--build_plt] [--add_to_plt] [--remove_from_plt]
-		[--check_plt] [--no_check_plt] [--plt_info] [--get_warnings]
-                [--dump_callgraph file] [--no_native] [--fullpath]
-                [--statistics] [--no_native_cache]</code>
-    <p>Options:</p>
+dialyzer [--add_to_plt] [--apps applications] [--build_plt]
+         [--check_plt] [-Ddefine]* [-Dname] [--dump_callgraph file]
+         [files_or_dirs] [--fullpath] [--get_warnings] [--gui] [--help]
+         [-I include_dir]* [--no_check_plt] [--no_native]
+         [--no_native_cache] [-o outfile] [--output_plt file] [-pa dir]*
+         [--plt plt] [--plt_info] [--plts plt*] [--quiet] [-r dirs]
+         [--raw] [--remove_from_plt] [--shell] [--src] [--statistics]
+         [--verbose] [--version] [-Wwarn]*</code>
+
+    <note>
+      <p>* denotes that multiple occurrences of the option are possible.</p>
+    </note>
+
+    <p><em>Options:</em></p>
+
     <taglist>
-      <tag><c><![CDATA[files_or_dirs]]></c> (for backwards compatibility also
-        as: <c><![CDATA[-c files_or_dirs]]></c>)</tag>
-      <item>Use Dialyzer from the command line to detect defects in the
-        specified files or directories containing <c><![CDATA[.erl]]></c> or
-         <c><![CDATA[.beam]]></c> files, depending on the type of the
-         analysis.</item>
-      <tag><c><![CDATA[-r dirs]]></c></tag>
-      <item>Same as the previous but the specified directories are searched
-        recursively for subdirectories containing <c><![CDATA[.erl]]></c> or
-        <c><![CDATA[.beam]]></c> files in them, depending on the type of
-        analysis.</item>
-      <tag><c><![CDATA[--apps applications]]></c></tag>
-      <item>Option typically used when building or modifying a plt as in:
+      <tag><c>--add_to_plt</c></tag>
+      <item>
+        <p>The PLT is extended to also include the files specified with
+          <c>-c</c> and <c>-r</c>. Use
+          <c>--plt</c> to specify which PLT to start from,
+          and <c>--output_plt</c> to specify where to put the PLT.
+          Notice that the analysis possibly can include files from the PLT if
+          they depend on the new files. This option only works for BEAM
+          files.</p>
+      </item>
+      <tag><c>--apps applications</c></tag>
+      <item>
+        <p>This option is typically used when building or modifying a PLT as
+          in:</p>
         <code type="none">
-           dialyzer --build_plt --apps erts kernel stdlib mnesia ...</code>
-        to conveniently refer to library applications corresponding to the
-        Erlang/OTP installation. However, the option is general and can also
-        be used during analysis in order to refer to Erlang/OTP applications.
-        In addition, file or directory names can also be included, as in:
+dialyzer --build_plt --apps erts kernel stdlib mnesia ...</code>
+        <p>to refer conveniently to library applications corresponding to the
+          Erlang/OTP installation. However, this option is general and can also
+          be used during analysis to refer to Erlang/OTP applications.
+          File or directory names can also be included, as in:</p>
         <code type="none">
-           dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam</code></item>
-      <tag><c><![CDATA[-o outfile]]></c> (or
-        <c><![CDATA[--output outfile]]></c>)</tag>
-      <item>When using Dialyzer from the command line, send the analysis
-        results to the specified outfile rather than to stdout.</item>
-      <tag><c><![CDATA[--raw]]></c></tag>
-      <item>When using Dialyzer from the command line, output the raw analysis
-        results (Erlang terms) instead of the formatted result. The raw format
-        is easier to post-process (for instance, to filter warnings or to
-        output HTML pages).</item>
-      <tag><c><![CDATA[--src]]></c></tag>
-      <item>Override the default, which is to analyze BEAM files, and
-        analyze starting from Erlang source code instead.</item>
-      <tag><c><![CDATA[-Dname]]></c> (or <c><![CDATA[-Dname=value]]></c>)</tag>
-      <item>When analyzing from source, pass the define to Dialyzer. (**)</item>
-      <tag><c><![CDATA[-I include_dir]]></c></tag>
-      <item>When analyzing from source, pass the <c><![CDATA[include_dir]]></c>
-        to Dialyzer. (**)</item>
-      <tag><c><![CDATA[-pa dir]]></c></tag>
-      <item>Include <c><![CDATA[dir]]></c> in the path for Erlang (useful when
-        analyzing files that have <c><![CDATA['-include_lib()']]></c>
-        directives).</item>
-      <tag><c><![CDATA[--output_plt file]]></c></tag>
-      <item>Store the plt at the specified file after building it.</item>
-      <tag><c><![CDATA[--plt plt]]></c></tag>
-      <item>Use the specified plt as the initial plt (if the plt was built
-        during setup the files will be checked for consistency).</item>
-      <tag><c><![CDATA[--plts plt*]]></c></tag>
-      <item>Merge the specified plts to create the initial plt -- requires
-        that the plts are disjoint (i.e., do not have any module
-        appearing in more than one plt).
-        The plts are created in the usual way:
+dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam</code>
+      </item>
+      <tag><c>--build_plt</c></tag>
+      <item>
+        <p>The analysis starts from an empty PLT and creates a new one from
+          the files specified with <c>-c</c> and
+          <c>-r</c>. This option only works for BEAM files.
+          To override the default PLT location, use
+          <c>--plt</c> or <c>--output_plt</c>.</p>
+      </item>
+      <tag><c>--check_plt</c></tag>
+      <item>
+        <p>Check the PLT for consistency and rebuild it if it is not
+          up-to-date.</p>
+      </item>
+      <tag><c>-Dname</c> (or <c>-Dname=value</c>)</tag>
+      <item>
+        <p>When analyzing from source, pass the define to Dialyzer.
+          (**)</p>
+      </item>
+      <tag><c>--dump_callgraph file</c></tag>
+      <item>
+        <p>Dump the call graph into the specified file whose format is
+          determined by the filename extension. Supported extensions are:
+          <c>raw</c>, <c>dot</c>, and <c>ps</c>. If something else is used as
+          filename extension, default format <c>.raw</c> is used.</p>
+      </item>
+      <tag><c>files_or_dirs</c> (for backward compatibility also
+        as <c>-c files_or_dirs</c>)</tag>
+      <item>
+        <p>Use Dialyzer from the command line to detect defects in the
+          specified files or directories containing <c>.erl</c> or
+          <c>.beam</c> files, depending on the type of the
+          analysis.</p>
+      </item>
+      <tag><c>--fullpath</c></tag>
+      <item>
+        <p>Display the full path names of files for which warnings are
+          emitted.</p>
+      </item>
+      <tag><c>--get_warnings</c></tag>
+      <item>
+        <p>Make Dialyzer emit warnings even when manipulating the PLT.
+          Warnings are only emitted for files that are analyzed.</p>
+      </item>
+      <tag><c>--gui</c></tag>
+      <item>
+        <p>Use the GUI.</p></item>
+      <tag><c>--help</c> (or <c>-h</c>)</tag>
+      <item>
+        <p>Print this message and exit.</p>
+      </item>
+      <tag><c>-I include_dir</c></tag>
+      <item>
+        <p>When analyzing from source, pass the <c>include_dir</c>
+          to Dialyzer. (**)</p>
+      </item>
+      <tag><c>--no_check_plt</c></tag>
+      <item>
+        <p>Skip the PLT check when running Dialyzer. This is useful when
+          working with installed PLTs that never change.</p>
+      </item>
+      <tag><c>--no_native</c> (or <c>-nn</c>)</tag>
+      <item>
+        <p>Bypass the native code compilation of some key files that
+          Dialyzer heuristically performs when dialyzing many files.
+          This avoids the compilation time, but can result in (much) longer
+          analysis time.</p>
+      </item>
+      <tag><c>--no_native_cache</c></tag>
+      <item>
+        <p>By default, Dialyzer caches the results of native compilation
+          in directory <c>$XDG_CACHE_HOME/erlang/dialyzer_hipe_cache</c>.
+          <c>XDG_CACHE_HOME</c> defaults to <c>$HOME/.cache</c>.
+          Use this option to disable caching.</p>
+      </item>
+      <tag><c>-o outfile</c> (or
+        <c>--output outfile</c>)</tag>
+      <item>
+        <p>When using Dialyzer from the command line, send the analysis
+          results to the specified outfile rather than to <c>stdout</c>.</p>
+      </item>
+      <tag><c>--output_plt file</c></tag>
+      <item>
+        <p>Store the PLT at the specified file after building it.</p>
+      </item>
+      <tag><c>-pa dir</c></tag>
+      <item>
+        <p>Include <c>dir</c> in the path for Erlang. This is useful
+          when analyzing files that have <c>-include_lib()</c>
+          directives.</p>
+      </item>
+      <tag><c>--plt plt</c></tag>
+      <item>
+        <p>Use the specified PLT as the initial PLT. If the PLT was built
+          during setup, the files are checked for consistency.</p>
+      </item>
+      <tag><c>--plt_info</c></tag>
+      <item>
+        <p>Make Dialyzer print information about the PLT and then quit.
+          The PLT can be specified with <c>--plt(s)</c>.</p>
+      </item>
+      <tag><c>--plts plt*</c></tag>
+      <item>
+        <p>Merge the specified PLTs to create the initial PLT. This requires
+          that the PLTs are disjoint (that is, do not have any module
+          appearing in more than one PLT).
+          The PLTs are created in the usual way:</p>
         <code type="none">
-           dialyzer --build_plt --output_plt plt_1 files_to_include
-           ...
-           dialyzer --build_plt --output_plt plt_n files_to_include</code>
-        and then can be used in either of the following ways:
+dialyzer --build_plt --output_plt plt_1 files_to_include
+...
+dialyzer --build_plt --output_plt plt_n files_to_include</code>
+        <p>They can then be used in either of the following ways:</p>
         <code type="none">
-           dialyzer files_to_analyze --plts plt_1 ... plt_n</code>
-        or:
+dialyzer files_to_analyze --plts plt_1 ... plt_n</code>
+        <p>or</p>
         <code type="none">
-           dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code>
-        (Note the -- delimiter in the second case)</item>
-      <tag><c><![CDATA[-Wwarn]]></c></tag>
-      <item>A family of options which selectively turn on/off warnings
-        (for help on the names of warnings use
-        <c><![CDATA[dialyzer -Whelp]]></c>).
-        Note that the options can also be given in the file with a
-        <c>-dialyzer()</c> attribute. See <seealso
-        marker="#suppression">Requesting or Suppressing Warnings in
-        Source Files</seealso> below for details.</item>
-      <tag><c><![CDATA[--shell]]></c></tag>
-      <item>Do not disable the Erlang shell while running the GUI.</item>
-      <tag><c><![CDATA[--version]]></c> (or <c><![CDATA[-v]]></c>)</tag>
-      <item>Print the Dialyzer version and some more information and
-        exit.</item>
-      <tag><c><![CDATA[--help]]></c> (or <c><![CDATA[-h]]></c>)</tag>
-      <item>Print this message and exit.</item>
-      <tag><c><![CDATA[--quiet]]></c> (or <c><![CDATA[-q]]></c>)</tag>
-      <item>Make Dialyzer a bit more quiet.</item>
-      <tag><c><![CDATA[--verbose]]></c></tag>
-      <item>Make Dialyzer a bit more verbose.</item>
-      <tag><c><![CDATA[--statistics]]></c></tag>
-      <item>Prints information about the progress of execution (analysis phases,
-      time spent in each and size of the relative input).</item>
-      <tag><c><![CDATA[--build_plt]]></c></tag>
-      <item>The analysis starts from an empty plt and creates a new one from
-        the files specified with <c><![CDATA[-c]]></c> and
-        <c><![CDATA[-r]]></c>. Only works for beam files. Use
-        <c><![CDATA[--plt]]></c> or <c><![CDATA[--output_plt]]></c> to
-        override the default plt location.</item>
-       <tag><c><![CDATA[--add_to_plt]]></c></tag>
-       <item>The plt is extended to also include the files specified with
-         <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c>. Use
-         <c><![CDATA[--plt]]></c> to specify which plt to start from,
-         and <c><![CDATA[--output_plt]]></c> to specify where to put the plt.
-         Note that the analysis might include files from the plt if they depend
-         on the new files. This option only works with beam files.</item>
-       <tag><c><![CDATA[--remove_from_plt]]></c></tag>
-       <item>The information from the files specified with
-         <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c> is removed
-         from the plt. Note that this may cause a re-analysis of the remaining
-         dependent files.</item>
-       <tag><c><![CDATA[--check_plt]]></c></tag>
-       <item>Check the plt for consistency and rebuild it if it is not
-         up-to-date.</item>
-       <tag><c><![CDATA[--no_check_plt]]></c></tag>
-       <item>Skip the plt check when running Dialyzer. Useful when working with
-         installed plts that never change.</item>
-       <tag><c><![CDATA[--plt_info]]></c></tag>
-       <item>Make Dialyzer print information about the plt and then quit. The
-         plt can be specified with <c><![CDATA[--plt(s)]]></c>.</item>
-       <tag><c><![CDATA[--get_warnings]]></c></tag>
-       <item>Make Dialyzer emit warnings even when manipulating the plt.
-         Warnings are only emitted for files that are actually analyzed.</item>
-       <tag><c><![CDATA[--dump_callgraph file]]></c></tag>
-       <item>Dump the call graph into the specified file whose format is
-         determined by the file name extension. Supported extensions are: raw,
-         dot, and ps. If something else is used as file name extension, default
-         format '.raw' will be used.</item>
-       <tag><c><![CDATA[--no_native]]></c> (or <c><![CDATA[-nn]]></c>)</tag>
-       <item>Bypass the native code compilation of some key files that Dialyzer
-         heuristically performs when dialyzing many files; this avoids the
-         compilation time but it may result in (much) longer analysis
-         time.</item>
-       <tag><c><![CDATA[--no_native_cache]]></c></tag>
-       <item>By default, Dialyzer caches the results of native compilation in the
-         <c>$XDG_CACHE_HOME/erlang/dialyzer_hipe_cache</c> directory.
-         <c>XDG_CACHE_HOME</c> defaults to <c>$HOME/.cache</c>.
-         Use this option to disable caching.</item>
-       <tag><c><![CDATA[--fullpath]]></c></tag>
-       <item>Display the full path names of files for which warnings are emitted.</item>
-       <tag><c><![CDATA[--gui]]></c></tag>
-       <item>Use the GUI.</item>
+dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code>
+        <p>Notice the <c>--</c> delimiter in the second case.</p>
+      </item>
+      <tag><c>--quiet</c> (or <c>-q</c>)</tag>
+      <item>
+        <p>Make Dialyzer a bit more quiet.</p>
+      </item>
+      <tag><c>-r dirs</c></tag>
+      <item>
+        <p>Same as <c>files_or_dirs</c>, but the specified
+          directories are searched
+          recursively for subdirectories containing <c>.erl</c> or
+          <c>.beam</c> files in them, depending on the type of
+          analysis.</p>
+      </item>
+      <tag><c>--raw</c></tag>
+      <item>
+        <p>When using Dialyzer from the command line, output the raw
+          analysis results (Erlang terms) instead of the formatted result.
+          The raw format
+          is easier to post-process (for example, to filter warnings or to
+          output HTML pages).</p>
+      </item>
+      <tag><c>--remove_from_plt</c></tag>
+      <item>
+        <p>The information from the files specified with
+          <c>-c</c> and <c>-r</c> is removed from
+          the PLT. Notice that this can cause a reanalysis of the remaining
+          dependent files.</p>
+      </item>
+      <tag><c>--shell</c></tag>
+      <item>
+        <p>Do not disable the Erlang shell while running the GUI.</p>
+      </item>
+      <tag><c>--src</c></tag>
+      <item>
+        <p>Override the default, which is to analyze BEAM files, and
+          analyze starting from Erlang source code instead.</p>
+      </item>
+      <tag><c>--statistics</c></tag>
+      <item>
+        <p>Print information about the progress of execution (analysis phases,
+          time spent in each, and size of the relative input).</p>
+      </item>
+      <tag><c>--verbose</c></tag>
+      <item>
+        <p>Make Dialyzer a bit more verbose.</p>
+      </item>
+      <tag><c>--version</c> (or <c>-v</c>)</tag>
+      <item>
+        <p>Print the Dialyzer version and some more information and
+          exit.</p>
+      </item>
+      <tag><c>-Wwarn</c></tag>
+      <item>
+        <p>A family of options that selectively turn on/off warnings.
+          (For help on the names of warnings, use
+          <c>dialyzer -Whelp</c>.)
+          Notice that the options can also be specified in the file with a
+          <c>-dialyzer()</c> attribute. For details, see section <seealso
+          marker="#suppression">Requesting or Suppressing Warnings in
+          Source Files</seealso>.</p>
+      </item>
     </taglist>
+
     <note>
-      <p>* denotes that multiple occurrences of these options are possible.</p>
-      <p>** options <c><![CDATA[-D]]></c> and <c><![CDATA[-I]]></c> work both from command-line and in the Dialyzer GUI;
-        the syntax of defines and includes is the same as that used by <c><![CDATA[erlc]]></c>.</p>
+      <p>** options <c>-D</c> and <c>-I</c> work both
+        from the command line and in the Dialyzer GUI; the syntax of
+        defines and includes is the same as that used by
+        <seealso marker="erts:erlc">erlc(1)</seealso>.</p>
     </note>
-    <p>Warning options:</p>
+
+    <p><em>Warning options:</em></p>
+
     <taglist>
-      <tag><c><![CDATA[-Wno_return]]></c></tag>
-      <item>Suppress warnings for functions that will never return a
-        value.</item>
-      <tag><c><![CDATA[-Wno_unused]]></c></tag>
-      <item>Suppress warnings for unused functions.</item>
-      <tag><c><![CDATA[-Wno_improper_lists]]></c></tag>
-      <item>Suppress warnings for construction of improper lists.</item>
-      <tag><c><![CDATA[-Wno_fun_app]]></c></tag>
-      <item>Suppress warnings for fun applications that will fail.</item>
-      <tag><c><![CDATA[-Wno_match]]></c></tag>
-      <item>Suppress warnings for patterns that are unused or cannot
-       match.</item>
-      <tag><c><![CDATA[-Wno_opaque]]></c></tag>
-      <item>Suppress warnings for violations of opaqueness of data types.</item>
-      <tag><c><![CDATA[-Wno_fail_call]]></c></tag>
-      <item>Suppress warnings for failing calls.</item>
-      <tag><c><![CDATA[-Wno_contracts]]></c></tag>
-      <item>Suppress warnings about invalid contracts.</item>
-      <tag><c><![CDATA[-Wno_behaviours]]></c></tag>
-      <item>Suppress warnings about behaviour callbacks which drift from the
-       published recommended interfaces.</item>
-      <tag><c><![CDATA[-Wno_missing_calls]]></c></tag>
-      <item>Suppress warnings about calls to missing functions.</item>
-      <tag><c><![CDATA[-Wno_undefined_callbacks]]></c></tag>
-      <item>Suppress warnings about behaviours that have no
-        <c>-callback</c> attributes for their callbacks.</item>
-      <tag><c><![CDATA[-Wunmatched_returns]]></c>***</tag>
-      <item>Include warnings for function calls which ignore a structured return
-        value or do not match against one of many possible return
-        value(s).</item>
-      <tag><c><![CDATA[-Werror_handling]]></c>***</tag>
-      <item>Include warnings for functions that only return by means of an
-       exception.</item>
-      <tag><c><![CDATA[-Wrace_conditions]]></c>***</tag>
-      <item>Include warnings for possible race conditions. Note that the
-      analysis that finds data races performs intra-procedural data flow analysis
-      and can sometimes explode in time. Enable it at your own risk.
-      </item>
-      <tag><c><![CDATA[-Wunderspecs]]></c>***</tag>
-      <item>Warn about underspecified functions
-      (the -spec is strictly more allowing than the success typing).</item>
-      <tag><c><![CDATA[-Wunknown]]></c>***</tag>
-      <item>Let warnings about unknown functions and types affect the
-      exit status of the command line version. The default is to ignore
-      warnings about unknown functions and types when setting the exit
-      status. When using the Dialyzer from Erlang, warnings about unknown
-      functions and types are returned; the default is not to return
-      these warnings.</item>
+      <tag><c>-Werror_handling</c> (***)</tag>
+      <item>
+        <p>Include warnings for functions that only return by an exception.</p>
+      </item>
+      <tag><c>-Wno_behaviours</c></tag>
+      <item>
+        <p>Suppress warnings about behavior callbacks that drift from the
+          published recommended interfaces.</p>
+      </item>
+      <tag><c>-Wno_contracts</c></tag>
+      <item>
+        <p>Suppress warnings about invalid contracts.</p>
+      </item>
+      <tag><c>-Wno_fail_call</c></tag>
+      <item>
+        <p>Suppress warnings for failing calls.</p>
+      </item>
+      <tag><c>-Wno_fun_app</c></tag>
+      <item>
+        <p>Suppress warnings for fun applications that will fail.</p>
+      </item>
+      <tag><c>-Wno_improper_lists</c></tag>
+      <item>
+        <p>Suppress warnings for construction of improper lists.</p>
+      </item>
+      <tag><c>-Wno_match</c></tag>
+      <item>
+        <p>Suppress warnings for patterns that are unused or cannot match.</p>
+      </item>
+      <tag><c>-Wno_missing_calls</c></tag>
+      <item>
+        <p>Suppress warnings about calls to missing functions.</p>
+      </item>
+      <tag><c>-Wno_opaque</c></tag>
+      <item>
+        <p>Suppress warnings for violations of opaqueness of data types.</p>
+      </item>
+      <tag><c>-Wno_return</c></tag>
+      <item>
+        <p>Suppress warnings for functions that will never return a value.</p>
+      </item>
+      <tag><c>-Wno_undefined_callbacks</c></tag>
+      <item>
+        <p>Suppress warnings about behaviors that have no
+          <c>-callback</c> attributes for their callbacks.</p>
+      </item>
+      <tag><c>-Wno_unused</c></tag>
+      <item>
+        <p>Suppress warnings for unused functions.</p>
+      </item>
+      <tag><c>-Wrace_conditions</c> (***)</tag>
+      <item>
+        <p>Include warnings for possible race conditions. Notice that the
+          analysis that finds data races performs intra-procedural data flow
+          analysis and can sometimes explode in time. Enable it at your own
+          risk.</p>
+      </item>
+      <tag><c>-Wunderspecs</c> (***)</tag>
+      <item>
+        <p>Warn about underspecified functions (the specification is strictly
+          more allowing than the success typing).</p>
+      </item>
+      <tag><c>-Wunknown</c> (***)</tag>
+      <item>
+        <p>Let warnings about unknown functions and types affect the
+          exit status of the command-line version. The default is to ignore
+          warnings about unknown functions and types when setting the exit
+          status. When using Dialyzer from Erlang, warnings about unknown
+          functions and types are returned; the default is not to return
+          these warnings.</p>
+      </item>
+      <tag><c>-Wunmatched_returns</c> (***)</tag>
+      <item>
+        <p>Include warnings for function calls that ignore a structured return
+          value or do not match against one of many possible return
+          value(s).</p>
+      </item>
     </taglist>
-    <p>The following options are also available but their use is not
-      recommended: (they are mostly for Dialyzer developers and internal
-      debugging)</p>
+
+    <p>The following options are also available, but their use is not
+      recommended (they are mostly for Dialyzer developers and internal
+      debugging):</p>
+
     <taglist>
-      <tag><c><![CDATA[-Woverspecs]]></c>***</tag>
-      <item>Warn about overspecified functions
-      (the -spec is strictly less allowing than the success typing).</item>
-      <tag><c><![CDATA[-Wspecdiffs]]></c>***</tag>
-      <item>Warn when the -spec is different than the success typing.</item>
+      <tag><c>-Woverspecs</c> (***)</tag>
+      <item>
+        <p>Warn about overspecified functions (the specification is strictly
+          less allowing than the success typing).</p>
+      </item>
+      <tag><c>-Wspecdiffs</c> (***)</tag>
+      <item>
+        <p>Warn when the specification is different than the success typing.</p>
+      </item>
     </taglist>
+
     <note>
-      <p>*** Identifies options that turn on warnings rather than
-      turning them off.</p>
+      <p>*** denotes options that turn on warnings rather than
+        turning them off.</p>
     </note>
   </section>
 
   <section>
-    <title>Using the Dialyzer from Erlang</title>
-    <p>You can also use Dialyzer directly from Erlang. Both the GUI and the
-      command line versions are available. The options are similar to the ones
-      given from the command line, so please refer to the sections above for
-      a description of these.</p>
+    <title>Using Dialyzer from Erlang</title>
+    <p>Dialyzer can be used directly from Erlang. Both the GUI and the
+      command-line versions are also available. The options are similar to the
+      ones given from the command line, see section
+      <seealso marker="#command_line">
+      Using Dialyzer from the Command Line</seealso>.</p>
   </section>
 
   <section>
     <marker id="suppression"></marker>
     <title>Requesting or Suppressing Warnings in Source Files</title>
-    <p>
-      The <c>-dialyzer()</c> attribute can be used for turning off
+    <p>Attribute <c>-dialyzer()</c> can be used for turning off
       warnings in a module by specifying functions or warning options.
       For example, to turn off all warnings for the function
-      <c>f/0</c>, include the following line:
-    </p>
-<code type="none">
--dialyzer({nowarn_function, f/0}).
-</code>
+      <c>f/0</c>, include the following line:</p>
+
+    <code type="none">
+-dialyzer({nowarn_function, f/0}).</code>
+
     <p>To turn off warnings for improper lists, add the following line
-      to the source file:
-    </p>
-<code type="none">
--dialyzer(no_improper_lists).
-</code>
-    <p>The <c>-dialyzer()</c> attribute is allowed after function
-    declarations. Lists of warning options or functions are allowed:
-    </p>
-<code type="none">
--dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).
-</code>
-    <p>
-      Warning options can be restricted to functions:
-    </p>
-<code type="none">
--dialyzer({no_improper_lists, g/0}).
-</code>
-<code type="none">
--dialyzer({[no_return, no_match], [g/0, h/0]}).
-</code>
-    <p>
-      For help on the warning options use <c>dialyzer -Whelp</c>. The
-      options are also enumerated <seealso
-      marker="#gui/1">below</seealso> (<c>WarnOpts</c>).
-    </p>
+      to the source file:</p>
+
+    <code type="none">
+-dialyzer(no_improper_lists).</code>
+
+    <p>Attribute <c>-dialyzer()</c> is allowed after function
+      declarations. Lists of warning options or functions are allowed:</p>
+
+    <code type="none">
+-dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).</code>
+
+    <p>Warning options can be restricted to functions:</p>
+
+    <code type="none">
+-dialyzer({no_improper_lists, g/0}).</code>
+
+    <code type="none">
+-dialyzer({[no_return, no_match], [g/0, h/0]}).</code>
+
+    <p>For help on the warning options, use <c>dialyzer -Whelp</c>. The
+      options are also enumerated, see function <seealso marker="#gui/1">
+      <c>gui/1</c></seealso> below (<c>WarnOpts</c>).</p>
+
     <note>
-      <p>
-        The <c>-dialyzer()</c> attribute is not checked by the Erlang
-              Compiler, but by the Dialyzer itself.
-      </p>
+      <p>Attribute <c>-dialyzer()</c> is not checked by the Erlang
+        compiler, but by Dialyzer itself.</p>
     </note>
+
     <note>
-      <p>
-        The warning option <c>-Wrace_conditions</c> has no effect when
-        set in source files.
-      </p>
+      <p>Warning option <c>-Wrace_conditions</c> has no effect when
+        set in source files.</p>
     </note>
-    <p>
-      The <c>-dialyzer()</c> attribute can also be used for turning on
-      warnings. For instance, if a module has been fixed regarding
-      unmatched returns, adding the line
-    </p>
-<code type="none">
--dialyzer(unmatched_returns).
-</code>
-    <p>
-      can help in assuring that no new unmatched return warnings are
-      introduced.
-    </p>
+
+    <p>Attribute <c>-dialyzer()</c> can also be used for turning on
+      warnings. For example, if a module has been fixed regarding
+      unmatched returns, adding the following line can help in assuring
+      that no new unmatched return warnings are introduced:</p>
+
+    <code type="none">
+-dialyzer(unmatched_returns).</code>
   </section>
 
   <funcs>
     <func>
+      <name>format_warning(Msg) -> string()</name>
+      <fsummary>Get the string version of a warning message.</fsummary>
+      <type>
+        <v>Msg = {Tag, Id, msg()}</v>
+        <d>See <c>run/1</c>.</d>
+      </type>
+      <desc>
+        <p>Get a string from warnings as returned by
+          <seealso marker="#run/1"><c>run/1</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
       <name>gui() -> ok | {error, Msg}</name>
       <name>gui(OptList) -> ok | {error, Msg}</name>
-      <fsummary>Dialyzer GUI version</fsummary>
+      <fsummary>Dialyzer GUI version.</fsummary>
       <type>
-        <v>OptList -- see below</v>
+        <v>OptList</v>
+        <d>See below.</d>
       </type>
       <desc>
         <p>Dialyzer GUI version.</p>
@@ -368,9 +504,12 @@ OptList  :: [Option]
 Option   :: {files,          [Filename :: string()]}
           | {files_rec,      [DirName :: string()]}
           | {defines,        [{Macro :: atom(), Value :: term()}]}
-          | {from,           src_code | byte_code}   %% Defaults to byte_code
-          | {init_plt,       FileName :: string()}   %% If changed from default
-          | {plts,           [FileName :: string()]} %% If changed from default
+          | {from,           src_code | byte_code}
+                               %% Defaults to byte_code
+          | {init_plt,       FileName :: string()}
+                               %% If changed from default
+          | {plts,           [FileName :: string()]}
+                               %% If changed from default
           | {include_dirs,   [DirName :: string()]}
           | {output_file,    FileName :: string()}
           | {output_plt,     FileName :: string()}
@@ -383,76 +522,71 @@ Option   :: {files,          [Filename :: string()]}
           | {warnings,       [WarnOpts]}
           | {get_warnings,   bool()}
 
-WarnOpts :: no_return
-          | no_unused
-          | no_improper_lists
+WarnOpts :: error_handling
+          | no_behaviours
+          | no_contracts
+          | no_fail_call
           | no_fun_app
+          | no_improper_lists
           | no_match
+	  | no_missing_calls
           | no_opaque
-          | no_fail_call
-          | no_contracts
-          | no_behaviours
+	  | no_return
           | no_undefined_callbacks
-          | unmatched_returns
-          | error_handling
+          | no_unused
           | race_conditions
-          | overspecs
           | underspecs
-          | specdiffs
-          | unknown</code>
+          | unknown
+          | unmatched_returns
+          | overspecs
+          | specdiffs</code>
       </desc>
     </func>
+
     <func>
-      <name>run(OptList) -> Warnings</name>
-      <fsummary>Dialyzer command line version</fsummary>
-      <type>
-        <v>OptList -- see gui/0,1</v>
-        <v>Warnings -- see below </v>
-      </type>
+      <name>plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}</name>
+      <fsummary>Return information about the specified PLT.</fsummary>
       <desc>
-        <p>Dialyzer command line version.</p>
-        <code type="none">
-Warnings :: [{Tag, Id, Msg}]
-Tag :: 'warn_behaviour'
-     | 'warn_bin_construction'
-     | 'warn_callgraph'
-     | 'warn_contract_not_equal'
-     | 'warn_contract_range'
-     | 'warn_contract_subtype'
-     | 'warn_contract_supertype'
-     | 'warn_contract_syntax'
-     | 'warn_contract_types'
-     | 'warn_failing_call'
-     | 'warn_fun_app'
-     | 'warn_matching'
-     | 'warn_non_proper_list'
-     | 'warn_not_called'
-     | 'warn_opaque'
-     | 'warn_race_condition'
-     | 'warn_return_no_exit'
-     | 'warn_return_only_exit'
-     | 'warn_umatched_return'
-     | 'warn_undefined_callbacks'
-     | 'warn_unknown'
-Id = {File :: string(), Line :: integer()}
-Msg = msg() -- Undefined</code>
+        <p>Returns information about the specified PLT.</p>
       </desc>
     </func>
+
     <func>
-      <name>format_warning(Msg) -> string()</name>
-      <fsummary>Get the string version of a warning message.</fsummary>
+      <name>run(OptList) -> Warnings</name>
+      <fsummary>Dialyzer command-line version.</fsummary>
       <type>
-        <v>Msg = {Tag, Id, msg()} -- See run/1</v>
+        <v>OptList</v>
+        <d>See <c>gui/0,1</c>.</d>
+        <v>Warnings</v>
+        <d>See below.</d>
       </type>
       <desc>
-        <p>Get a string from warnings as returned by dialyzer:run/1.</p>
-      </desc>
-    </func>
-    <func>
-      <name>plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}</name>
-      <fsummary>Returns information about the specified plt.</fsummary>
-      <desc>
-        <p>Returns information about the specified plt.</p>
+        <p>Dialyzer command-line version.</p>
+        <code type="none">
+Warnings :: [{Tag, Id, Msg}]
+Tag      :: 'warn_behaviour'
+          | 'warn_bin_construction'
+          | 'warn_callgraph'
+          | 'warn_contract_not_equal'
+          | 'warn_contract_range'
+          | 'warn_contract_subtype'
+          | 'warn_contract_supertype'
+          | 'warn_contract_syntax'
+          | 'warn_contract_types'
+          | 'warn_failing_call'
+          | 'warn_fun_app'
+          | 'warn_matching'
+          | 'warn_non_proper_list'
+          | 'warn_not_called'
+          | 'warn_opaque'
+          | 'warn_race_condition'
+          | 'warn_return_no_exit'
+          | 'warn_return_only_exit'
+          | 'warn_umatched_return'
+          | 'warn_undefined_callbacks'
+          | 'warn_unknown'
+Id  = {File :: string(), Line :: integer()}
+Msg = msg() -- Undefined</code>
       </desc>
     </func>
   </funcs>
diff --git a/lib/dialyzer/doc/src/dialyzer_chapter.xml b/lib/dialyzer/doc/src/dialyzer_chapter.xml
index c445f2633f..b5acf3732e 100644
--- a/lib/dialyzer/doc/src/dialyzer_chapter.xml
+++ b/lib/dialyzer/doc/src/dialyzer_chapter.xml
@@ -25,196 +25,211 @@
     <title>Dialyzer</title>
     <prepared></prepared>
     <docno></docno>
-    <date></date>
+    <date>2016-09-19</date>
     <rev></rev>
     <file>dialyzer_chapter.xml</file>
   </header>
 
   <section>
     <title>Introduction</title>
-    <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies
-      such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules
-      or entire (sets of) applications.</p>
-  </section>
-
-  <section>
-    <title>Using the Dialyzer from the GUI</title>
-
     <section>
-      <title>Choosing the applications or modules</title>
-      <p>In the "File" window you will find a listing of the current directory.
-        Click your way to the directories/modules you want to add or type the
-        correct path in the entry.</p>
-      <p>Mark the directories/modules you want to analyze for discrepancies and
-        click "Add". You can either add the <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-files directly, or
-        you can add directories that contain these kinds of files. Note that
-        you are only allowed to add the type of files that can be analyzed in
-        the current mode of operation (see below), and that you cannot mix
-        <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-files.</p>
+      <title>Scope</title>
+      <p>Dialyzer is a static analysis tool that identifies software
+        discrepancies, such as definite type errors, code that has become dead
+        or unreachable because of programming error, and unnecessary tests,
+        in single Erlang modules or entire (sets of) applications.</p>
+
+      <p>Dialyzer can be called from the command line, from Erlang,
+        and from a GUI.</p>
     </section>
 
     <section>
-      <title>The analysis modes</title>
-      <p>Dialyzer has two modes of analysis, "Byte Code" or "Source Code". 
-         These are controlled by the buttons in the top-middle part of the 
-         main window, under "Analysis Options".</p>
-    </section>
-
-    <section>
-      <title>Controlling the discrepancies reported by the Dialyzer</title>
-      <p>Under the "Warnings" pull-down menu, there are buttons that control
-        which discrepancies are reported to the user in the "Warnings" window.
-        By clicking on these buttons, one can enable/disable a whole class of
-        warnings.  Information about the classes of warnings can be found on
-        the "Warnings" item under the "Help" menu (at the rightmost top corner).</p>
-      <p>If modules are compiled with inlining, spurious warnings may be emitted.
-        In the "Options" menu you can choose to ignore inline-compiled modules
-        when analyzing byte code. When starting from source code this is not a
-        problem since the inlining is explicitly turned off by Dialyzer. The
-        option causes Dialyzer to suppress all warnings from inline-compiled
-        modules, since there is currently no way for Dialyzer to find what
-        parts of the code have been produced by inlining. </p>
+      <title>Prerequisites</title>
+      <p>It is assumed that the reader is familiar with the Erlang programming
+        language.</p>
     </section>
+  </section>
 
-    <section>
-      <title>Running the analysis</title>
-      <p>Once you have chosen the modules or directories you want to analyze,
-        click the "Run" button to start the analysis. If for some reason you
-        want to stop the analysis while it is running, push the "Stop" button.</p>
-      <p>The information from the analysis will be displayed in the Log and the
-        Warnings windows.</p>
-    </section>
+  <section>
+    <marker id="plt"/>
+    <title>The Persistent Lookup Table</title>
+    <p>Dialyzer stores the result of an analysis in a Persistent
+      Lookup Table (PLT). The PLT can then be used as a starting
+      point for later analyses. It is recommended to build a PLT with the
+      Erlang/OTP applications that you are using, but also to include your
+      own applications that you are using frequently.</p>
+
+    <p>The PLT is built using option <c>--build_plt</c> to Dialyzer.
+      The following command builds the recommended minimal PLT for
+      Erlang/OTP:</p>
 
-    <section>
-      <title>Include directories and macro definitions</title>
-      <p>When analyzing from source you might have to supply Dialyzer with a
-        list of include directories and macro definitions (as you can do with
-        the <c><![CDATA[erlc]]></c> flags <c><![CDATA[-I]]></c> and <c><![CDATA[-D]]></c>). This can be done either by starting Dialyzer
-        with these flags from the command line as in:</p>
-      <code type="none">
+    <code type="none">
+dialyzer --build_plt --apps erts kernel stdlib mnesia</code>
 
-      dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir
-      </code>
-      <p>or by adding these explicitly using the "Manage Macro Definitions" or
-        "Manage Include Directories" sub-menus in the "Options" menu.</p>
-    </section>
+    <p>Dialyzer looks if there is an environment variable called
+      <c>DIALYZER_PLT</c> and places the PLT at this location. If no such
+      variable is set, Dialyzer places the PLT at
+      <c>$HOME/.dialyzer_plt</c>. The placement can also be specified using
+      the options <c>--plt</c> or <c>--output_plt</c>.</p>
 
-    <section>
-      <title>Saving the information on the Log and Warnings windows</title>
-      <p>In the "File" menu there are options to save the contents of the Log
-        and the Warnings window. Just choose the options and enter the file to
-        save the contents in.</p>
-      <p>There are also buttons to clear the contents of each window.</p>
-    </section>
+    <p>Information can be added to an existing PLT using option
+      <c>--add_to_plt</c>. If you also want to include the Erlang compiler in
+      the PLT and place it in a new PLT, then use the following command:</p>
 
-    <section>
-      <title>Inspecting the inferred types of the analyzed functions</title>
-      <p>Dialyzer stores the information of the analyzed functions in a
-        Persistent Lookup Table (PLT). After an analysis you can inspect this
-        information. In the PLT menu you can choose to either search the PLT
-        or inspect the contents of the whole PLT. The information is presented
-        in edoc format.</p>
-    </section>
-  </section>
+    <code type="none">
+dialyzer --add_to_plt --apps compiler --output_plt my.plt</code>
 
-  <section>
-    <title>Using the Dialyzer from the command line</title>
-    <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p>
-  </section>
+    <p>Then you can add your favorite application my_app to the new
+      PLT:</p>
 
-  <section>
-    <title>Using the Dialyzer from Erlang</title>
-    <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p>
-  </section>
+    <code type="none">
+dialyzer --add_to_plt --plt my.plt -r my_app/ebin</code>
 
-  <section>
-    <title>More on the Persistent Lookup Table (PLT)</title> 
+    <p>But you realize that it is unnecessary to have the Erlang compiler in this
+      one:</p>
 
-    <p> The persistent lookup table, or PLT, is used to store the
-    result of an analysis. The PLT can then be used as a starting
-    point for later analyses. It is recommended to build a PLT with
-    the otp applications that you are using, but also to include your
-    own applications that you are using frequently.</p>
+    <code type="none">
+dialyzer --remove_from_plt --plt my.plt --apps compiler</code>
 
-    <p>The PLT is built using the --build_plt option to dialyzer. The
-    following command builds the recommended minimal PLT for OTP.</p>
+    <p>Later, when you have fixed a bug in your application my_app,
+      you want to update the PLT so that it becomes fresh the next time
+      you run Dialyzer. In this case, run the following command:</p>
 
     <code type="none">
+dialyzer --check_plt --plt my.plt</code>
 
-    dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin\
-                            $ERL_TOP/lib/kernel/ebin \
-                            $ERL_TOP/lib/mnesia/ebin
-    </code>
+    <p>Dialyzer then reanalyzes the changed files
+      and the files that depend on these files. Notice that this
+      consistency check is performed automatically the next time you
+      run Dialyzer with this PLT. Option <c>--check_plt</c> is only
+      for doing so without doing any other analysis.</p>
 
-    <p>Dialyzer will look if there is an environment variable called
-    $DIALYZER_PLT and place the PLT at this location. If no such
-    variable is set, Dialyzer will place the PLT at
-    $HOME/.dialyzer_plt. The placement can also be specified using the
-    --plt, or --output_plt options.</p>
-
-    <p>You can also add information to an existing plt using the
-    --add_to_plt option. Suppose you want to also include the compiler
-    in the PLT and place it in a new PLT, then give the command</p>
+    <p>To get information about a PLT, use the following option:</p>
 
     <code type="none">
+dialyzer --plt_info</code>
 
-    dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt
-    </code>
+    <p>To specify which PLT, use option <c>--plt</c>.</p>
 
-    <p>Then you would like to add your favorite application my_app to
-    the new plt.</p>
+    <p>To get the output printed to a file, use option <c>--output_file</c>.</p>
 
-    <code type="none">
+    <p>Notice that when manipulating the PLT, no warnings are
+      emitted. To turn on warnings during (re)analysis of the PLT, use
+      option <c>--get_warnings</c>.</p>
+  </section>
 
-    dialyzer --add_to_plt --plt my.plt -r my_app/ebin
-    </code>
+  <section>
+    <title>Using Dialyzer from the Command Line</title>
+    <p>Dialyzer has a command-line version for automated use.
+      See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p>
+  </section>
 
-    <p>But you realize that it is unnecessary to have compiler in this one.</p>
+  <section>
+    <title>Using Dialyzer from Erlang</title>
+    <p>Dialyzer can also be used directly from Erlang.
+      See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p>
+  </section>
 
-    <code type="none">
+  <section>
+   <marker id="dialyzer_gui"/>
+    <title>Using Dialyzer from the GUI</title>
+    <section>
+      <title>Choosing the Applications or Modules</title>
+      <p>The <em>File</em> window displays a listing of the current directory.
+        Click your way to the directories/modules you want to add or type the
+        correct path in the entry.</p>
 
-    dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin
-    </code>
+      <p>Mark the directories/modules you want to analyze for discrepancies and
+        click <em>Add</em>. You can either add the <c>.beam</c> and
+        <c>.erl</c> files directly, or add directories that contain
+        these kind of files. Notice that
+        you are only allowed to add the type of files that can be analyzed in
+        the current mode of operation (see below), and that you cannot mix
+        <c>.beam</c> and <c>.erl</c> files.</p>
+    </section>
 
-    <p> Later, when you have fixed a bug in your application my_app,
-    you want to update the plt so that it will be fresh the next time
-    you run Dialyzer, run the command</p>
+    <section>
+      <title>Analysis Modes</title>
+      <p>Dialyzer has two analysis modes: "Byte Code" and "Source Code".
+         They are controlled by the buttons in the top-middle part of the
+         main window, under <em>Analysis Options</em>.</p>
+    </section>
 
-    <code type="none">
+    <section>
+      <title>Controlling the Discrepancies Reported by Dialyzer</title>
+      <p>Under the <em>Warnings</em> pull-down menu, there are buttons that
+        control which discrepancies are reported to the user in the
+        <em>Warnings</em> window. By clicking these buttons, you can
+        enable/disable a whole class of warnings. Information about the classes
+        of warnings is found on the "Warnings" item under the <em>Help</em>
+        menu (in the rightmost top corner).</p>
+
+      <p>If modules are compiled with inlining, spurious warnings can be
+        emitted. In the <em>Options</em> menu you can choose to ignore
+        inline-compiled modules when analyzing byte code.
+        When starting from source code, this is not a problem because
+        inlining is explicitly turned off by Dialyzer. The option causes
+        Dialyzer to suppress all warnings from inline-compiled
+        modules, as there is currently no way for Dialyzer to find what
+        parts of the code have been produced by inlining.</p>
+    </section>
 
-    dialyzer --check_plt --plt my.plt
-    </code>
+    <section>
+      <title>Running the Analysis</title>
+      <p>Once you have chosen the modules or directories you want to analyze,
+        click the <em>Run</em> button to start the analysis. If you for some
+        reason want to stop the analysis while it is running, click the
+        <em>Stop</em> button.</p>
 
-    <p> Dialyzer will then reanalyze the files that have been changed,
-    and the files that depend on these files. Note that this
-    consistency check will be performed automatically the next time
-    you run Dialyzer with this plt. The --check_plt option is merely
-    for doing so without doing any other analysis.</p>
+      <p>The information from the analysis is displayed in the <em>Log</em>
+        window and the <em>Warnings</em> window.</p>
+    </section>
 
-    <p> To get some information about a plt use the option</p>
-    <code type="none">
+    <section>
+      <title>Include Directories and Macro Definitions</title>
+      <p>When analyzing from source, you might have to supply Dialyzer
+        with a list of include directories and macro definitions (as you can do
+        with the <seealso marker="erts:erlc"><c>erlc</c></seealso> flags
+        <c>-I</c> and <c>-D</c>). This can be done
+        either by starting Dialyzer with these flags from the command
+        line as in:</p>
+
+      <code type="none">
+dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir</code>
 
-    dialyzer --plt_info
-    </code>
+      <p>or by adding these explicitly using submenu
+        <em>Manage Macro Definitions</em> or
+        <em>Manage Include Directories</em> in the <em>Options</em> menu.</p>
+    </section>
 
-    <p>You can also specify which plt with the --plt option, and get the 
-    output printed to a file with --output_file</p>
+    <section>
+      <title>Saving the Information on the Log and Warnings Windows</title>
+      <p>The <em>File</em> menu includes options to save the contents of the
+        <em>Log</em> window and the <em>Warnings</em> window. Simply choose the
+        options and enter the file to save the contents in.</p>
 
-    <p>Note that when manipulating the plt, no warnings are
-    emitted. To turn on warnings during (re)analysis of the plt, use
-    the option --get_warnings.</p>
+      <p>There are also buttons to clear the contents of each window.</p>
+    </section>
 
+    <section>
+      <title>Inspecting the Inferred Types of the Analyzed Functions</title>
+      <p>Dialyzer stores the information of the analyzed functions in a
+        Persistent Lookup Table (PLT), see section
+        <seealso marker="#plt">The Persistent Lookup Table</seealso>.</p>
+
+      <p>After an analysis, you can inspect this information.
+        In the <em>PLT</em> menu you can choose to either search the PLT
+        or inspect the contents of the whole PLT. The information is presented
+        in <seealso marker="edoc:edoc"><c>EDoc</c></seealso> format.</p>
+    </section>
   </section>
 
   <section>
-    <title>Feedback and bug reports</title>
-    <p>At this point, we very much welcome user feedback (even wish-lists!).
-      If you notice something weird, especially if the Dialyzer reports any
-      discrepancy that is a false positive, please send an error report
-      describing the symptoms and how to reproduce them to:</p>
-    <code type="none"><![CDATA[
-    [email protected], [email protected]
-    ]]></code>
+    <title>Feedback and Bug Reports</title>
+    <p>We very much welcome user feedback - even wishlists!
+      If you notice anything weird, especially if Dialyzer reports
+      any discrepancy that is a false positive, please send an error report
+      describing the symptoms and how to reproduce them.</p>
   </section>
 </chapter>
 
diff --git a/lib/dialyzer/doc/src/part.xml b/lib/dialyzer/doc/src/part.xml
index 575f77549a..9bfcf21a66 100644
--- a/lib/dialyzer/doc/src/part.xml
+++ b/lib/dialyzer/doc/src/part.xml
@@ -25,12 +25,11 @@
     <title>Dialyzer User's Guide</title>
     <prepared></prepared>
     <docno></docno>
-    <date></date>
+    <date>2016-09-19</date>
     <rev></rev>
     <file>part.xml</file>
   </header>
   <description>
-    <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.</p>
   </description>
   <xi:include href="dialyzer_chapter.xml"/>
 </part>
diff --git a/lib/dialyzer/doc/src/ref_man.xml b/lib/dialyzer/doc/src/ref_man.xml
index 01478cfb40..ddac047f2e 100644
--- a/lib/dialyzer/doc/src/ref_man.xml
+++ b/lib/dialyzer/doc/src/ref_man.xml
@@ -25,11 +25,10 @@
     <title>Dialyzer Reference Manual</title>
     <prepared></prepared>
     <docno></docno>
-    <date></date>
+    <date>2016-09-19</date>
     <rev></rev>
   </header>
   <description>
-    <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.</p>
   </description>
   <xi:include href="dialyzer.xml"/>
 </application>