Add scope, motivation, and software review information to generated software-READMEs

code/drasil-code/lib/Language/Drasil/Code/Imperative/GOOL/ClassInterface.hs

@@ -52,6 +52,8 @@ type CaseName = String
 type ExamplePurpose = String
 -- | Description of example
 type ExampleDescr = String
+-- | Motivation of example
+type ExampleMotivation = String
 -- | File contributors
 type Contributor = String
 -- | Holds all information needed to create a README file.
@@ -66,5 +68,6 @@ data ReadMeInfo = ReadMeInfo {
   configFP :: [FilePath],
   caseName :: CaseName,
   examplePurpose :: ExamplePurpose,
-  exampleDescr :: ExampleDescr
+  exampleDescr :: ExampleDescr,
+  exampleMotivation :: ExampleMotivation
 }

code/drasil-code/lib/Language/Drasil/Code/Imperative/Generator.hs

@@ -133,9 +133,11 @@ genPackage unRepr = do
       cfp = configFiles $ codeSpec g
       db = sysinfodb $ codeSpec g
       prps = show $ sentenceDoc db Implementation Linear 
-        (foldlSent $ purpose $ codeSpec g)
+        (foldlSent_ $ purpose $ codeSpec g)
       bckgrnd = show $ sentenceDoc db Implementation Linear 
-        (foldlSent $ background $ codeSpec g)  
+        (foldlSent_ $ background $ codeSpec g)
+      mtvtn = show $ sentenceDoc db Implementation Linear 
+        (foldlSent_ $ motivation $ codeSpec g)      
   i <- genSampleInput
   d <- genDoxConfig s
   rm <- genReadMe ReadMeInfo {
@@ -149,7 +151,8 @@ genPackage unRepr = do
         configFP = cfp,
         caseName = "",
         examplePurpose = prps,
-        exampleDescr = bckgrnd}
+        exampleDescr = bckgrnd,
+        exampleMotivation = mtvtn}
   return $ package pd (m:catMaybes [i,rm,d])
 
 -- | Generates an SCS program based on the problem and the user's design choices.

code/drasil-code/lib/Language/Drasil/Code/Imperative/WriteReadMe.hs

@@ -24,8 +24,9 @@ makeReadMe ReadMeInfo {
         configFP = configFPs,
         caseName = name,
         examplePurpose = purp,
-        exampleDescr = descr} = 
-    makeMd [introInfo name auths $ fieldEmptySTR purp,
+        exampleDescr = descr,
+        exampleMotivation = motiv} = 
+    makeMd [introInfo name auths (fieldEmptySTR purp) (fieldEmptySTR motiv),
     whatInfo $ fieldEmptySTR descr,
     makeInstr imptype configFPs,
     verInfo progLang progLangVers,

code/drasil-code/lib/Language/Drasil/CodeSpec.hs

@@ -49,6 +49,12 @@ data CodeSpec where
   purpose :: Purpose,
   -- | Example Background.
   background :: Background,
+  -- | Example Scope.
+  scope :: Scope,
+  -- | Example Software Review.
+  sftwr_rev :: SoftwareReview,
+  -- | Example Motivation.
+  motivation :: Motivation,
   -- | All inputs.
   inputs :: [Input],
   -- | Explicit inputs (values to be supplied by a file).
@@ -100,6 +106,9 @@ codeSpec SI {_sys         = sys
            , _authors     = as
            , _purpose     = ps
            , _background  = bk
+           , _scope       = scp
+           , _sftwr_rev   = sfrv
+           , _motivation  = mtvtn
            , _instModels  = ims
            , _datadefs    = ddefs
            , _configFiles = cfp
@@ -125,6 +134,9 @@ codeSpec SI {_sys         = sys
         authors = as,
         purpose = ps,
         background = bk,
+        scope = scp,
+        sftwr_rev = sfrv,
+        motivation  = mtvtn,
         inputs = allInputs,
         extInputs = inputs',
         derivedInputs = derived,

code/drasil-example/dblpendulum/lib/Drasil/DblPendulum/Body.hs

@@ -107,6 +107,9 @@ si = SI {
   _authors     = [dong],
   _purpose     = [],
   _background  = [], 
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants      = symbolsAll,
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = iMods,

code/drasil-example/gamephysics/lib/Drasil/GamePhysics/Body.hs

@@ -104,6 +104,9 @@ si = SI {
   _authors     = [alex, luthfi, olu],
   _purpose     = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   -- FIXME: The _quants field should be filled in with all the symbols, however
   -- #1658 is why this is empty, otherwise we end up with unused (and probably
   -- should be removed) symbols. But that's for another time. This is "fine"

code/drasil-example/glassbr/lib/Drasil/GlassBR/Body.hs

@@ -67,6 +67,9 @@ si = SI {
   _authors     = [nikitha, spencerSmith],
   _purpose     = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants      = symbolsForTable,
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = iMods,

code/drasil-example/hghc/lib/Drasil/HGHC/Body.hs

@@ -30,6 +30,9 @@ si = SI {
   _quants      = symbols,
   _purpose     = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _concepts    = [] :: [UnitalChunk],
   _instModels  = [], -- FIXME; empty _instModels
   _datadefs    = dataDefs,

code/drasil-example/nopcm/lib/Drasil/NoPCM/Body.hs

@@ -176,6 +176,9 @@ si = SI {
   _authors     = [thulasi],
   _purpose     = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   -- FIXME: Everything after (and including) \\ should be removed when
   -- #1658 is resolved. Basically, _quants is used here, but 
   -- tau does not appear in the document and thus should not be displayed.

code/drasil-example/pdcontroller/lib/Drasil/PDController/Body.hs

@@ -104,6 +104,9 @@ si = SI {
   _authors = [naveen],
   _purpose = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants = symbolsAll,
   _concepts = [] :: [DefinedQuantityDict],
   _datadefs = dataDefinitions,

code/drasil-example/projectile/lib/Drasil/Projectile/Body.hs

@@ -1,5 +1,6 @@
 module Drasil.Projectile.Body (printSetting, si, srs, projectileTitle, fullSI) where
 
+import Control.Lens ((^.))
 import Language.Drasil
 import Drasil.SRSDocument
 import Language.Drasil.Chunk.Concept.NamedCombinators
@@ -67,7 +68,7 @@ mkSRS = [TableOfContents,
       [ SSDProblem $ PDProg prob []
         [ TermsAndDefs Nothing terms
         , PhySysDesc projectileTitle physSystParts figLaunch []
-        , Goals [(phrase iVel +:+ S "vector") `S.the_ofThe` phrase projectile]]
+        , Goals [inputsPhrase]]
       , SSDSolChSpec $ SCSProg
         [ Assumptions
         , TMs [] (Label : stdFields)
@@ -89,9 +90,24 @@ mkSRS = [TableOfContents,
   Bibliography
   ]
 
+inputsPhrase :: Sentence
+inputsPhrase = (phrase iVel +:+ S "vector") `S.the_ofThe` phrase projectile
+
+purpose :: Sentence
+purpose = foldlSent_ [S "Given", inputsPhrase `sC` phrase projectileTitle, S "will"] +:+ 
+  foldlSent_ (map (^. defn) goals)
+
+background :: Sentence
+background = foldlSent [S "Common examples of", phrase projectile, phrase motion, S "include",
+    S "ballistics", plural problem, S "(missiles and bullets)" `S.andThe` S "flight of the balls",
+    S "in various sports (baseball, golf, football, etc.)"]
+
+motivation :: Sentence
+motivation = foldlSent [atStart projectile, phrase motion, S "is a common" +:+
+  phraseNP (problem `in_` physics)]
+
 justification, scope :: Sentence
-justification = foldlSent [atStart projectile, phrase motion, S "is a common" +:+.
-  phraseNP (problem `in_` physics), S "Therefore, it is useful to have a",
+justification = foldlSent [motivation, S "Therefore, it is useful to have a",
   phrase program, S "to solve and model these types of" +:+. plural problem,
   atStartNP (the program), S "documented here is called", phrase projectileTitle]
 scope = foldlSent_ [phraseNP (NP.the (analysis `ofA` twoD)),
@@ -106,8 +122,11 @@ si = SI {
   _sys         = projectileTitle,
   _kind        = Doc.srs,
   _authors     = [samCrawford, brooks, spencerSmith],
-  _purpose     = [],
-  _background  = [],
+  _purpose     = [purpose],
+  _background  = [background],
+  _motivation  = [motivation],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants      = symbols,
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = iMods,

code/drasil-example/projectile/lib/Drasil/Projectile/Lesson/Body.hs

@@ -52,7 +52,10 @@ si = SI {
   _kind        = Doc.notebook,
   _authors     = [spencerSmith],
   _purpose     = [],
-  _background  = [], 
+  _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [], 
   _quants      = [] :: [QuantityDict],
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = [],

code/drasil-example/sglpendulum/lib/Drasil/SglPendulum/Body.hs

@@ -108,6 +108,9 @@ si = SI {
   _authors     = [olu],
   _purpose     = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants      = symbols,
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = iMods,

code/drasil-example/ssp/lib/Drasil/SSP/Body.hs

@@ -75,6 +75,9 @@ si = SI {
   _authors     = [henryFrankis, brooks],
   _purpose     = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants      = symbols,
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = SSP.iMods,

code/drasil-example/swhs/lib/Drasil/SWHS/Body.hs

@@ -80,6 +80,9 @@ si = SI {
   _authors     = [thulasi, brooks, spencerSmith],
   _purpose     = [],
   _background  = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants      = symbols,
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = insModel,

code/drasil-example/template/lib/Drasil/Template/Body.hs

@@ -31,6 +31,9 @@ si = SI {
   _authors     = [authorName],
   _background  = [],
   _purpose     = [],
+  _motivation  = [],
+  _scope       = [],
+  _sftwr_rev   = [],
   _quants      = [] :: [QuantityDict],
   _concepts    = [] :: [DefinedQuantityDict],
   _instModels  = [] :: [InstanceModel],

code/drasil-gen/lib/Language/Drasil/TypeCheck.hs

@@ -13,7 +13,7 @@ import SysInfo.Drasil (SystemInformation(SI))
 
 typeCheckSI :: SystemInformation -> IO ()
 typeCheckSI
-  (SI _ _ _ _ _ _ _ ims dds _ _ _ _ _ _ chks _ _)
+  (SI _ _ _ _ _ _ _ _ _ _ ims dds _ _ _ _ _ _ chks _ _)
   = do
     -- build a variable context (a map of UIDs to "Space"s [types])
     let cxt = M.map (\(dict, _) -> dict ^. typ) (symbolTable chks)

code/drasil-printers/lib/Language/Drasil/Markdown/CreateMd.hs

@@ -18,18 +18,24 @@ makeMd :: [Doc] -> Doc
 makeMd = vcat . punctuate secSep . filtEmp
 
 -- | Example title, authors, and maybe purpose section.
-introInfo :: String -> [String] -> Maybe String -> Doc
-introInfo name auths descr = introSec (text name) (listToDoc auths) (length auths) (maybePurpDoc descr)
+introInfo :: String -> [String] -> Maybe String -> Maybe String -> Doc
+introInfo name auths descr motiv = introSec (text name) (prepName name)
+  (listToDoc auths) (length auths) (maybeSub "Purpose" descr) (maybeSub "Motivation" motiv)
+
+-- | Helper for prepending the example name.
+prepName :: String -> Doc
+prepName name = text "> The program documented here is called" <+> text name <> text "."
 
 -- | Instruction section, contains 3 paragraphs, Running, Building and Config Files.
 -- The Config file section is only displayed if there are configuration files.
 instDoc :: [String] -> Doc
 instDoc cfp = regularSec (text "Making Examples") 
     (runInstDoc <> doubleSep <> makeInstDoc) <> configSec cfp 
 
--- | Helper for creating optional Purpose subsection as Doc
-maybePurpDoc :: Maybe String -> Doc
-maybePurpDoc = maybe empty (\descr-> doubleSep <> text "> Purpose:" <+> text descr)
+-- | Helper for creating optional Intro subsection as Doc
+maybeSub :: String -> Maybe String -> Doc
+maybeSub role = maybe empty (\content-> doubleSep <> text ("> " ++ role ++ ":") 
+  <+> text content)
 
 -- | 'What' section in generated README file, does not display if empty
 whatInfo :: Maybe String -> Doc
@@ -125,9 +131,9 @@ bkQuote3 = text "```"
 -- FIXME as explained in #2224 we still need to add in the purpose section, 
 -- this could be done by adding a third parameter to introSec
 -- | Constructs introduction section from header and message.
-introSec ::  Doc -> Doc -> Int -> Doc -> Doc
-introSec hd ms1 l descr = text "#" <+> hd <+> contSep <> (if l == 1 then text "> Author:" else text "> Authors: ") 
-  <+> ms1 <> descr
+introSec ::  Doc -> Doc -> Doc -> Int -> Doc -> Doc -> Doc
+introSec hd name ms1 l descr motiv = text "#" <+> hd <+> contSep <> name <> doubleSep <> 
+  (if l == 1 then text "> Author:" else text "> Authors: ") <+> ms1 <> descr <> motiv
 
 -- | Constructs regular section section from header and message.
 regularSec :: Doc -> Doc -> Doc

code/drasil-sysinfo/lib/SysInfo/Drasil.hs

@@ -2,8 +2,8 @@ module SysInfo.Drasil (
  -- * System Information
    SystemInformation(..), Block(Parallel), sysinfodb
  -- * Reference Database
- , ReferenceDB, RefMap, Purpose, Background, citeDB, rdb, simpleMap
- , citationDB, conceptDB
+ , ReferenceDB, RefMap, Purpose, Background, Scope, SoftwareReview, Motivation
+ , citeDB, rdb, simpleMap, citationDB, conceptDB
 
   -- ** Utility Helper Functions
   -- GetChunk

code/drasil-sysinfo/lib/SysInfo/Drasil/SystemInformation.hs

@@ -10,13 +10,13 @@ module SysInfo.Drasil.SystemInformation (
   -- ** Types
   SystemInformation(..), Block(..),
   -- ** Lenses
-  instModels, datadefs, configFiles, inputs, purpose, background,
-  defSequence, constraints, constants, sysinfodb, usedinfodb,
+  instModels, datadefs, configFiles, inputs, purpose, background, scope, sftwr_rev,
+  motivation, defSequence, constraints, constants, sysinfodb, usedinfodb,
   -- ** Lookup Functions
   citeDB, citationsFromBibMap,
   -- * Reference Database
   -- ** Types
-  ReferenceDB, RefMap, Purpose, Background,
+  ReferenceDB, RefMap, Purpose, Background, Scope, SoftwareReview, Motivation,
   -- ** Constructors
   rdb, simpleMap,
   -- ** Lenses
@@ -50,6 +50,9 @@ data SystemInformation where
   , _authors     :: [c]
   , _purpose     :: Purpose
   , _background  :: Background
+  , _scope       :: Scope
+  , _sftwr_rev   :: SoftwareReview
+  , _motivation  :: Motivation
   , _quants      :: [e]
   , _concepts    :: [f]
   , _instModels  :: [InstanceModel]
@@ -70,6 +73,12 @@ data SystemInformation where
 type Purpose = [Sentence]
 -- | Project Example background information, used in the 'What' section of README.
 type Background = [Sentence]
+-- | Project Example scope.
+type Scope = [Sentence]
+-- | Project Example software revision.
+type SoftwareReview = [Sentence]
+-- | Project Example motivation.
+type Motivation = [Sentence]
 
 -- | for listing 'QDefinition's in 'SystemInformation'.
 data Block a = Coupled a a [a] | Parallel a [a]

code/drasil-website/lib/Drasil/Website/Body.hs

@@ -65,6 +65,9 @@ si fl = SI {
     _quants      = [] :: [QuantityDict],
     _purpose     = [],
     _background  = [],
+    _motivation  = [],
+    _scope       = [],
+    _sftwr_rev   = [],
     _concepts    = [] :: [UnitalChunk],
     _instModels  = [],
     _datadefs    = [],