clarify the behavior of note.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@64748 91177308-0d34-0410-b5e6-96231b3b80d8

docs/InternalsManual.html

@@ -161,20 +161,31 @@ produce diagnostics to tell the user their code is non-portable.  The difference
 is that the former are ignored by default, and the later warn by default.  The
 <tt>WARNING</tt> severity is used for constructs that are valid in the currently
 selected source language but that are dubious in some way.  The <tt>NOTE</tt>
-level is used to staple more information onto a previous diagnostics.</p>
+level is used to staple more information onto a previous diagnostics.
 
 <p>These <em>severities</em> are mapped into a smaller set (the
 Diagnostic::Level enum, {<tt>Ignored</tt>, <tt>Note</tt>, <tt>Warning</tt>,
 <tt>Error</tt>, <tt>Fatal</tt> }) of output <em>levels</em> by the diagnostics
-subsystem based
-on various configuration options.  For example, if the user specifies
-<tt>-pedantic</tt>, <tt>EXTENSION</tt> maps to <tt>Warning</tt>, if they specify
-<tt>-pedantic-errors</tt>, it turns into <tt>Error</tt>.  Clang also internally
-supports a fully fine grained mapping mechanism that allows you to map any
-diagnostic that doesn't have <tt>ERRROR</tt> severity to any output level that
-you want.  This is used to implement options like <tt>-Wunused_macros</tt>,
-<tt>-Wundef</tt> etc.  Fatal errors are considered so severe that diagnostics
-that occur after them are supressed as "almost certainly useless".</p>
+subsystem based on various configuration options.  Clang internally supports a
+fully fine grained mapping mechanism that allows you to map almost any
+diagnostic to the output level that you want.  The only diagnostics that cannot
+be mapped are <tt>NOTE</tt>s, which always follow the severity of the previously
+emitted diagnostic and <tt>ERROR</tt>s, which can only be mapped to
+<tt>Fatal</tt> (it is not possible to turn an error into a warning,
+for example).</p>
+
+<p>Diagnostic mappings are used in many ways.  For example, if the user
+specifies <tt>-pedantic</tt>, <tt>EXTENSION</tt> maps to <tt>Warning</tt>, if
+they specify <tt>-pedantic-errors</tt>, it turns into <tt>Error</tt>.  This is
+used to implement options like <tt>-Wunused_macros</tt>, <tt>-Wundef</tt> etc.
+</p>
+
+<p>
+Mapping to <tt>Fatal</tt> should only be used for diagnostics that are
+considered so severe that error recovery won't be able to recover sensibly from
+them (thus spewing a ton of bogus errors).  One example of this class of error
+are failure to #include a file.
+</p>
 
 <!-- ================= -->
 <h4>The Format String</h4>