[commit: ghc] master: docs: Add mentions of new plugins mechanisms to users guide (da53417)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/da534170b6d1560e46d6966b488100701d9177ec/ghc

>---------------------------------------------------------------

commit da534170b6d1560e46d6966b488100701d9177ec
Author: Ben Gamari <ben at smart-cactus.org>
Date:   Tue Jun 12 09:57:14 2018 -0400

    docs: Add mentions of new plugins mechanisms to users guide


>---------------------------------------------------------------

da534170b6d1560e46d6966b488100701d9177ec
 docs/users_guide/8.6.1-notes.rst   | 31 +++++++++++++++++++++++++++++++
 docs/users_guide/extending_ghc.rst |  2 +-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/docs/users_guide/8.6.1-notes.rst b/docs/users_guide/8.6.1-notes.rst
index 366e94b..ef9a6b6 100644
--- a/docs/users_guide/8.6.1-notes.rst
+++ b/docs/users_guide/8.6.1-notes.rst
@@ -126,6 +126,37 @@ Compiler
   :ghc-flag:`-fexternal-dynamic-refs`. If you don't know why you might
   need this, you don't need it.
 
+Plugins
+~~~~~~~
+
+- GHC's plugin mechanism now offers plugin authors control over their plugin's
+  effect on recompilation checking. Specifically the ``Plugin`` record name has
+  a new field ::
+
+    data Plugin = Plugin {
+        pluginRecompile :: [CommandLineOption] -> IO PluginRecompile
+      , {- ... -}
+      }
+
+    data PluginRecompile = ForceRecompile | NoForceRecompile | MaybeRecompile Fingerprint
+
+  Plugin based on ``defaultPlugin`` will have their previous recompilation
+  behavior (``ForceRecompile``) preserved. However, plugins that are "pure" are
+  encouraged to override this to either ``NoForceRecompile`` or ``MaybeRecompile``.
+  See :ref:`plugin_recompilation` for details.
+
+- GHC now provides a class of new plugins: source plugins. These plugins can
+  inspect and modify a variety of intermediate representations used by the
+  compiler's frontend. These include:
+
+    * The ability to modify the parser output
+    * The ability to inspect the renamer output
+    * The ability to modify the typechecked AST
+    * The ability to modify Template Haskell splices
+    * The ability to modify interface files as they are loaded
+
+  See :ref:`source-plugins` for details.
+
 GHCi
 ~~~~
 
diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst
index a0d3db6..97f2143 100644
--- a/docs/users_guide/extending_ghc.rst
+++ b/docs/users_guide/extending_ghc.rst
@@ -612,7 +612,7 @@ plugins is to make it easier to implement development tools.
 There are several different access points that you can use for defining plugins
 that access the representations. All these fields receive the list of
 ``CommandLineOption`` strings that are passed to the compiler using the
-``-fplugin-opt`` flags.
+:ghc-flag:`-fplugin-opt` flags.
 
 ::