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 = [],