Merge remote-tracking branch 'origin/master' into wip/orf-rebootwip/orf-reboot

Conflicts:
	compiler/rename/RnNames.hs
	compiler/typecheck/TcRnMonad.hs
	utils/haddock

1 files changed, 98 insertions, 53 deletions

diff --git a/utils/mkUserGuidePart/Main.hs b/utils/mkUserGuidePart/Main.hs
index c415eb4f49..9bc8caa216 100644
--- a/utils/mkUserGuidePart/Main.hs
+++ b/utils/mkUserGuidePart/Main.hs
@@ -1,62 +1,107 @@
-
 module Main (main) where
 
 import DynFlags
+import Data.List (stripPrefix)
+import Control.Monad (forM_)
+import Types hiding (flag)
+import Table
+import Options
 
-import Data.List
-import System.Environment
+-- | A ReStructuredText fragment
+type ReST = String
 
 main :: IO ()
-main = do args <- getArgs
-          case args of
-              [] -> error "Need to give filename to generate as an argument"
-              [f] ->
-                  case f of
-                      "docs/users_guide/users_guide.xml" ->
-                          writeFile f userGuideMain
-                      "docs/users_guide/what_glasgow_exts_does.gen.xml" ->
-                          writeFile f whatGlasgowExtsDoes
-                      _ ->
-                          error ("Don't know what to do for " ++ show f)
-              _ -> error "Bad args"
-
--- Hack: dblatex normalises the name of the main input file using
--- os.path.realpath, which means that if we're in a linked build tree,
--- it find the real source files rather than the symlinks in our link
--- tree. This is fine for the static sources, but it means it can't
--- find the generated sources.
--- We therefore also generate the main input file, so that it really
--- is in the link tree, and thus dblatex can find everything.
-userGuideMain :: String
-userGuideMain = unlines [
-    "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>",
-    "<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.2//EN\"",
-    "   \"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\" [",
-    "<!ENTITY % ug-ent SYSTEM \"ug-ent.xml\">",
-    "%ug-ent;",
-    "<!ENTITY ug-book SYSTEM \"ug-book.xml\">",
-    "]>",
-    "",
-    "<book id=\"users-guide\">",
-    "&ug-book;",
-    "</book>"]
+main = do
+  -- users guide
+  writeRestFile (usersGuideFile "what_glasgow_exts_does.gen.rst")
+    $ whatGlasgowExtsDoes
+  forM_ groups $ \(Group name _ theFlags) ->
+    let fname = usersGuideFile $ "flags-"++name++".gen.rst"
+    in writeRestFile fname (flagsTable theFlags)
+
+  -- man page
+  writeRestFile (usersGuideFile "all-flags.gen.rst") (flagsList groups)
+
+usersGuideFile :: FilePath -> FilePath
+usersGuideFile fname = "docs/users_guide/"++fname
+
+writeRestFile :: FilePath -> ReST -> IO ()
+writeRestFile fname content =
+  writeFile fname $ unlines
+    [ ".. This file is generated by utils/mkUserGuidePart"
+    , ""
+    , content
+    ]
 
 whatGlasgowExtsDoes :: String
-whatGlasgowExtsDoes = case maybeInitLast glasgowExtsFlags of
-                      Just (xs, x) ->
-                          let xs' = map mkInitLine xs
-                              x' = mkLastLine x
-                          in unlines (xs' ++ [x'])
-                      Nothing ->
-                          error "glasgowExtsFlags is empty?"
-    where mkInitLine = mkLine ','
-          mkLastLine = mkLine '.'
-          mkLine c f = case stripPrefix "Opt_" (show f) of
-                       Just ext -> "<option>-X" ++ ext ++ "</option>" ++ [c]
-                       Nothing -> error ("Can't parse extension: " ++ show f)
-
-maybeInitLast :: [a] -> Maybe ([a], a)
-maybeInitLast xs = case reverse xs of
-                   (y : ys) -> Just (reverse ys, y)
-                   _        -> Nothing
+whatGlasgowExtsDoes = unlines
+    $ [ ".. hlist::", ""]
+    ++ map ((" * "++) . parseExt) glasgowExtsFlags
+  where
+    parseExt f
+      | Just ext <- stripPrefix "Opt_" (show f)
+      = inlineCode $ "-X" ++ ext
+      | otherwise
+      = error ("Can't parse extension: " ++ show f)
+
+-- | Generate a reference table of the given set of flags. This is used in
+-- the users guide.
+flagsTable :: [Flag] -> ReST
+flagsTable theFlags =
+    table [50, 100, 30, 50]
+          ["Flag", "Description", "Static/Dynamic", "Reverse"]
+          (map flagRow theFlags)
+  where
+    code ""  = ""
+    code str = "``"++str++"``"
+    flagRow flag =
+        [ code (flagName flag)
+        , flagDescription flag
+        , type_
+        , code (flagReverse flag)
+        ]
+      where
+        type_ = case flagType flag of
+                  StaticFlag          -> "static"
+                  DynamicFlag         -> "dynamic"
+                  DynamicSettableFlag -> "dynamic/``:set``"
+                  ModeFlag            -> "mode"
+
+-- | Place the given text in an ReST inline code element.
+inlineCode :: String -> ReST
+inlineCode s = "``" ++ s ++ "``"
+
+-- | Generate a ReST substitution definition.
+substitution :: String -> ReST -> ReST
+substitution substName content =
+    unlines [".. |" ++ substName ++ "| ", content]
+
+heading :: Char -> String -> ReST
+heading chr title = unlines
+    [ title
+    , replicate (length title) chr
+    , ""
+    ]
+
+-- | Generate a listing of all the flags known to GHC.
+-- Used in the man page.
+flagsList :: [Group] -> ReST
+flagsList grps = unlines $
+    map doGroup grps ++ map flagDescriptions grps
+  where
+    doGroup grp = unlines
+      [ grpTitle grp
+      , "    " ++ unwords (map (inlineCode . flagName) (grpFlags grp))
+      , ""
+      ]
 
+-- | Generate a definition list of the known flags.
+-- Used in the man page.
+flagDescriptions :: Group -> ReST
+flagDescriptions (Group _ title fs) =
+    unlines $ [ heading '~' title ] ++ map doFlag fs
+  where
+    doFlag flag =
+      unlines $ [ inlineCode (flagName flag)
+                , "    " ++ flagDescription flag
+                ]