Add "System Context" section to SSP (#934)

* removed Verbatim GSD implementation from SSP

* added SystemContextFigure.png to datafiles subfolder

* added system context section to ssp

* updated import lists to remove some redundancies and errors

* reinserted missing subsection; fixed typo

* updated stable for System Context section introduction

code/drasil-docLang/Drasil/DocumentLanguage.hs

@@ -159,7 +159,7 @@ data GSDSec = GSDVerb Section
 
 data GSDSub where
  GSDSubVerb :: Section -> GSDSub
- SysCntxt :: [Contents] -> GSDSub
+ SysCntxt :: [Contents] -> GSDSub --FIXME: partially automate
  UsrChars :: [Contents] -> GSDSub
  SystCons :: [Contents] -> [Section] -> GSDSub
 

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

@@ -9,15 +9,16 @@ import Drasil.DocLang (DocDesc, DocSection(..), IntroSec(..), IntroSub(..),
  LCsSec(..), LFunc(..), RefSec(..), RefTab(..), TConvention(..), --TSIntro, 
  TSIntro(..), UCsSec(..), Fields, Field(..), SSDSec(..), SSDSub(..),
  Verbosity(..), InclUnits(..), DerivationDisplay(..), SolChSpec(..),
- SCSSub(..),
- dataConstraintUncertainty, genSysF, goalStmtF, 
- inDataConstTbl, intro, mkDoc, nonFuncReqF, outDataConstTbl, probDescF, reqF, 
- termDefnF, tsymb'', valsOfAuxConstantsF)
-
-import Data.Drasil.Concepts.Documentation (analysis, 
- design, document, effect, element, endUser, goalStmt, inModel, input_, 
- interest, interest, issue, loss, method_, organization, physics, 
- problem, property, requirement, srs, table_, template, value, variable)
+ SCSSub(..), GSDSec(..), GSDSub(..),
+ dataConstraintUncertainty, goalStmtF, inDataConstTbl, intro, mkDoc, 
+ nonFuncReqF, outDataConstTbl, probDescF, reqF, termDefnF, tsymb'',
+ valsOfAuxConstantsF)
+
+import Data.Drasil.Concepts.Documentation (analysis, assumption,
+ design, document, effect, element, endUser, environment, goalStmt, inModel, 
+ input_, interest, interest, interface, issue, loss, method_, organization, 
+ physics, problem, product_, property, requirement, software, softwareSys, 
+ srs, sysCont, system, table_, template, user, value, variable)
 import Data.Drasil.Concepts.Education (solidMechanics, undergraduate)
 import Data.Drasil.Concepts.Math (equation, surface)
 import Data.Drasil.Concepts.PhysicalProperties (mass)
@@ -31,15 +32,15 @@ import Data.Drasil.Software.Products (sciCompS)
 import Data.Drasil.People (henryFrankis)
 import Data.Drasil.Phrase (for)
 import Data.Drasil.SentenceStructures (foldlList, foldlSP, foldlSent, 
- foldlSent_, ofThe, sAnd, sOr)
+ foldlSent_, ofThe, sAnd, sOr, foldlSPCol)
 import Data.Drasil.SI_Units (degree, metre, newton, pascal)
-import Data.Drasil.Utils (enumBullet, enumSimple, noRefsLT)
+import Data.Drasil.Utils (enumBullet, enumSimple, noRefsLT, bulletNested, bulletFlat)
 import Drasil.SSP.Assumptions (sspRefDB)
 import Drasil.SSP.Changes (likelyChanges_SRS, unlikelyChanges_SRS)
 import Drasil.SSP.DataDefs (dataDefns)
 import Drasil.SSP.DataDesc (sspInputMod)
 import Drasil.SSP.Defs (acronyms, crtSlpSrf, fs_concept, intrslce, itslPrpty, 
- morPrice, mtrlPrpty, plnStrn, slice, slope, slpSrf, soil, soilLyr, ssa)
+ morPrice, mtrlPrpty, plnStrn, slice, slope, slpSrf, soil, soilLyr, ssa, ssp)
 import Drasil.SSP.GenDefs (generalDefinitions)
 import Drasil.SSP.Goals (sspGoals)
 import Drasil.SSP.IMods (sspIMods_new)
@@ -49,10 +50,10 @@ import Drasil.SSP.TMods (fs_rc_new, equilibrium_new, mcShrStrgth_new, hookesLaw_
 import Drasil.SSP.Unitals (fs, index, numbSlices, sspConstrained, sspInputs, 
  sspOutputs, sspSymbols)
 
-import qualified Drasil.DocLang.SRS as SRS (funcReq, inModel, missingP, physSyst)
+import qualified Drasil.DocLang.SRS as SRS (funcReq, assumpt, inModel, missingP, physSyst)
 
 --type declarations for sections--
-gen_sys_desc, req, aux_cons :: Section
+req, aux_cons :: Section
 
 table_of_symbol_intro :: [TSIntro]
 
@@ -89,7 +90,7 @@ resourcePath :: String
 resourcePath = "../../../datafiles/SSP/"
 
 ssp_srs :: Document
-ssp_srs = mkDoc mkSRS (for) ssp_si
+ssp_srs = mkDoc mkSRS for ssp_si
 
 mkSRS :: DocDesc
 mkSRS = RefSec (RefProg intro
@@ -102,8 +103,8 @@ mkSRS = RefSec (RefProg intro
  EmptyS
  , IOrgSec orgSecStart inModel (SRS.inModel SRS.missingP []) orgSecEnd]) :
  --FIXME: issue #235
- Verbatim gen_sys_desc: 
- ------
+ (GSDSec $ GSDProg2 [SysCntxt [sysCtxIntro, sysCtxFig1, sysCtxDesc, sysCtxList], 
+  UsrChars [userCharIntro], SystCons [] []]):
  SSDSec 
  (SSDProg [SSDSubVerb problem_desc
  , SSDSolChSpec 
@@ -120,7 +121,7 @@ mkSRS = RefSec (RefProg intro
  ]
  )
  ]
-  ):
+ ):
  map Verbatim [req] ++ [LCsSec (LCsProg likelyChanges_SRS)] 
  ++ [UCsSec (UCsProg unlikelyChanges_SRS)] ++[Verbatim aux_cons] ++ (Bibliography : [])
 
@@ -228,10 +229,53 @@ orgSecEnd = S "The" +:+ plural inModel +:+ S "provide the set of" +:+
  +:+ S "to perform a" +:+ titleize morPrice +:+ titleize analysis
 
 -- SECTION 3 --
-gen_sys_desc = genSysF [] userCharIntro [] []
-
 -- SECTION 3.1 --
--- User Characteristics automatically generated in genSysF with the
+-- System Context automatically generated
+sysCtxIntro :: Contents
+sysCtxIntro = foldlSP
+ [makeRef sysCtxFig1 +:+ S "shows the" +:+. phrase sysCont,
+ S "A circle represents an external entity outside the" +:+ phrase software
+ `sC` S "the", phrase user, S "in this case. A rectangle represents the",
+ phrase softwareSys, S "itself" +:+. (sParen $ short ssp),
+ S "Arrows are used to show the data flow between the" +:+ phrase system,
+ S "and its" +:+ phrase environment]
+
+sysCtxFig1 :: Contents
+sysCtxFig1 = fig (titleize sysCont) (resourcePath ++ "SystemContextFigure.png") "sysCtxDiag"
+
+sysCtxDesc :: Contents
+sysCtxDesc = foldlSPCol
+ [S "The interaction between the", phrase product_, S "and the", phrase user,
+ S "is through a user" +:+. phrase interface,
+ S "The responsibilities of the", phrase user, S "and the", phrase system,
+ S "are as follows"]
+
+sysCtxUsrResp :: [Sentence]
+sysCtxUsrResp = [S "Provide the input data related to the soil layer(s) and water" +:+
+ S "table (if applicable), ensuring no errors in the data entry",
+ S "Ensure that consistent units are used for input variables",
+ S "Ensure required" +:+ phrase software +:+ plural assumption +:+ sParen ( 
+ makeRef (SRS.assumpt SRS.missingP [])) +:+ S "are appropriate for any particular" +:+
+ phrase problem +:+ S "input to the" +:+ phrase software]
+
+sysCtxSysResp :: [Sentence]
+sysCtxSysResp = [S "Detect data type mismatch, such as a string of characters" +:+ 
+ S " input instead of a floating point number",
+ S "Determine if the inputs satisfy the required physical and software constraints",
+ S "Identify the most likely failure surface within the possible input range",
+ S "Find the factor of safety for the slope",
+ S "Find the displacement of soil that will occur on the slope"]
+
+sysCtxResp :: [Sentence]
+sysCtxResp = [titleize user +:+ S "Responsibilities",
+ short ssp +:+ S "Responsibilities"]
+
+sysCtxList :: Contents
+sysCtxList = Enumeration $ bulletNested sysCtxResp $
+ map bulletFlat [sysCtxUsrResp, sysCtxSysResp]
+
+-- SECTION 3.2 --
+-- User Characteristics automatically generated with the
 -- userContraints intro below
 
 userCharIntro :: Contents
@@ -246,7 +290,7 @@ userChar pname understandings familiarities = foldlSP [
  S "and be familiar with", foldlList familiarities]
 
 -- SECTION 3.2 --
--- System Constraints automatically generated in genSysF
+-- System Constraints automatically generated
 
 -- SECTION 4 --
 
@@ -385,4 +429,4 @@ non_func_req = nonFuncReqF [accuracy, performanceSpd]
 aux_cons = valsOfAuxConstantsF ssa []
 
 -- References --
--- automatically generated
+-- automatically generated

code/stable/ssp/SRS/SSP_SRS.tex

@@ -289,6 +289,33 @@ \subsection{Organization of Document}
 \section{General System Description}
 \label{Sec:GenSysDesc}
 This section provides general information about the system including identifying the interfaces between the system and its environment (system context), describing the user characteristics and listing the system constraints.
+\subsection{System Context}
+\label{Sec:SysContext}
+Figure~\ref{Figure:sysCtxDiag} shows the system context. A circle represents an external entity outside the software, the user in this case. A rectangle represents the software system itself (SSP). Arrows are used to show the data flow between the system and its environment.
+\begin{figure}
+\begin{center}
+\includegraphics[width=\textwidth]{../../../datafiles/SSP/SystemContextFigure.png}
+\caption{System Context}
+\label{Figure:sysCtxDiag}
+\end{center}
+\end{figure}
+The interaction between the product and the user is through a user interface. The responsibilities of the user and the system are as follows:
+\begin{itemize}
+\item{User Responsibilities}
+\begin{itemize}
+\item{Provide the input data related to the soil layer(s) and water table (if applicable), ensuring no errors in the data entry}
+\item{Ensure that consistent units are used for input variables}
+\item{Ensure required software assumptions (Section~\ref{Sec:Assumps}) are appropriate for any particular problem input to the software}
+\end{itemize}
+\item{SSP Responsibilities}
+\begin{itemize}
+\item{Detect data type mismatch, such as a string of characters input instead of a floating point number}
+\item{Determine if the inputs satisfy the required physical and software constraints}
+\item{Identify the most likely failure surface within the possible input range}
+\item{Find the factor of safety for the slope}
+\item{Find the displacement of soil that will occur on the slope}
+\end{itemize}
+\end{itemize}
 \subsection{User Characteristics}
 \label{Sec:UserChars}
 The end user of SSA should have an understanding of undergraduate Level 1 Calculus and Physics, and be familiar with soil and material properties.

code/stable/ssp/Website/SSP_SRS.html

@@ -1211,6 +1211,61 @@ <h1>
 <p class="paragraph">
 This section provides general information about the system including identifying the interfaces between the system and its environment (system context), describing the user characteristics and listing the system constraints.
 </p>
+<div id="Sec:SysContext">
+<div class="subsection">
+<h2>
+System Context
+</h2>
+<p class="paragraph">
+<a href=#Figure:sysCtxDiag>Figure:sysCtxDiag</a> shows the system context. A circle represents an external entity outside the software, the user in this case. A rectangle represents the software system itself (SSP). Arrows are used to show the data flow between the system and its environment.
+</p>
+<div id="Figure:sysCtxDiag">
+<img class="figure" src="../../../datafiles/SSP/SystemContextFigure.png" alt="System Context"></img>
+<p class="caption">
+System Context
+</p>
+</div>
+<p class="paragraph">
+The interaction between the product and the user is through a user interface. The responsibilities of the user and the system are as follows:
+</p>
+<ul class="list">
+<li>
+User Responsibilities
+<ul class="list">
+<li>
+Provide the input data related to the soil layer(s) and water table (if applicable), ensuring no errors in the data entry
+</li>
+<li>
+Ensure that consistent units are used for input variables
+</li>
+<li>
+Ensure required software assumptions (<a href=#Sec:Assumps>Assumptions</a>) are appropriate for any particular problem input to the software
+</li>
+</ul>
+</li>
+<li>
+SSP Responsibilities
+<ul class="list">
+<li>
+Detect data type mismatch, such as a string of characters input instead of a floating point number
+</li>
+<li>
+Determine if the inputs satisfy the required physical and software constraints
+</li>
+<li>
+Identify the most likely failure surface within the possible input range
+</li>
+<li>
+Find the factor of safety for the slope
+</li>
+<li>
+Find the displacement of soil that will occur on the slope
+</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
 <div id="Sec:UserChars">
 <div class="subsection">
 <h2>