FIX #1847 (improve :browse! docs, fix unqual)

- add example to docs, explain how to interpret 
  output of `:browse! Data.Maybe`
- print unqualified names according to current 
  context, not the context of the target module

compiler/ghci/InteractiveUI.hs

@@ -167,8 +167,8 @@ helpText =
  "   <statement>                 evaluate/run <statement>\n" ++
  "   :{\\n ..lines.. \\n:}\\n       multiline command\n" ++
  "   :add <filename> ...         add module(s) to the current target set\n" ++
- "   :browse[!] [-s] [[*]<mod>]  display the names defined by module <mod>\n" ++
- "                               (!: more details; -s: sort; *: all top-level names)\n" ++
+ "   :browse[!] [[*]<mod>]       display the names defined by module <mod>\n" ++
+ "                               (!: more details; *: all top-level names)\n" ++
  "   :cd <dir>                   change directory to <dir>\n" ++
  "   :cmd <expr>                 run the commands returned by <expr>::IO String\n" ++
  "   :ctags [<file>]             create tags file for Vi (default: \"tags\")\n" ++
@@ -1171,15 +1171,19 @@ browseCmd bang m =
 browseModule :: Bool -> Module -> Bool -> GHCi ()
 browseModule bang modl exports_only = do
   s <- getSession
+  -- :browse! reports qualifiers wrt current context
+  current_unqual <- io (GHC.getPrintUnqual s)
   -- Temporarily set the context to the module we're interested in,
   -- just so we can get an appropriate PrintUnqualified
   (as,bs) <- io (GHC.getContext s)
   prel_mod <- getPrelude
   io (if exports_only then GHC.setContext s [] [prel_mod,modl]
                       else GHC.setContext s [modl] [])
-  unqual <- io (GHC.getPrintUnqual s)
+  target_unqual <- io (GHC.getPrintUnqual s)
   io (GHC.setContext s as bs)
 
+  let unqual = if bang then current_unqual else target_unqual
+
   mb_mod_info <- io $ GHC.getModuleInfo s modl
   case mb_mod_info of
     Nothing -> throwDyn (CmdLineError ("unknown module: " ++
@@ -1220,7 +1224,7 @@ browseModule bang modl exports_only = do
             labels  [] = text "-- not currently imported"
             labels  l  = text $ intercalate "\n" $ map qualifier l
             qualifier  = maybe "-- defined locally" 
-                             (("-- imported from "++) . intercalate ", " 
+                             (("-- imported via "++) . intercalate ", " 
                                . map GHC.moduleNameString)
             importInfo = RdrName.getGRE_NameQualifier_maybes rdr_env
             modNames   = map (importInfo . GHC.getName) things

docs/users_guide/ghci.xml

@@ -1740,6 +1740,32 @@ $ ghci -lm
     The <literal>!</literal>-form also annotates the listing 
     with comments giving possible imports for each group of 
     entries.</para>
+<screen>
+Prelude> :browse! Data.Maybe
+-- not currently imported
+Data.Maybe.catMaybes :: [Maybe a] -> [a]
+Data.Maybe.fromJust :: Maybe a -> a
+Data.Maybe.fromMaybe :: a -> Maybe a -> a
+Data.Maybe.isJust :: Maybe a -> Bool
+Data.Maybe.isNothing :: Maybe a -> Bool
+Data.Maybe.listToMaybe :: [a] -> Maybe a
+Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b]
+Data.Maybe.maybeToList :: Maybe a -> [a]
+-- imported via Prelude
+Just :: a -> Maybe a
+data Maybe a = Nothing | Just a
+Nothing :: Maybe a
+maybe :: b -> (a -> b) -> Maybe a -> b
+</screen>
+  <para>
+    This output shows that, in the context of the current session, in the scope
+    of <literal>Prelude</literal>, the first group of items from
+    <literal>Data.Maybe</literal> have not been imported (but are available in
+    fully qualified form in the GHCi session - see <xref
+      linkend="ghci-scope"/>), whereas the second group of items have been
+    imported via <literal>Prelude</literal> and are therefore available either
+    unqualified, or with a <literal>Prelude.</literal> qualifier.
+  </para>
 	</listitem>
       </varlistentry>