SWHS Intro Revision

[danscime]

I feel like the grammar in this sentence should be revised.

[smiths]

Agreed. What do you propose?

[danscime]

Maybe "The main purpose of this document is to describe the modelling of a solar water heating system."
Very very minor.

[bmaclach]

It seems like the original text was intending to refer to the program by name, but the capitalization was incorrect. Like it was intended to be "... describe the modelling of Solar Water Heating System".

[smiths]

@bmaclach's advice makes sense. This section is the purpose of the document, not the purpose of the software. The purpose of the document is to describe SWHS. Do we use the acronym SWHS in the SRS for SWHS? I actually think we could take out the word "modelling." The high level view of the purpose of the document is "to describe SWHS." We aren't giving a model of the software; the software itself is a model of the real-world, but our document is the requirements for the software, not a model of the requirements.

[danscime]

So should we go with "The main purpose of this document is to describe Solar Water Heating System."?

Or something like "The main purpose of this document is to describe the Solar Water Heating System program."?

[smiths]

@danscime, I like the second one, since we want to make it clear that we are talking about software. I think we should change the word program to software. I also took out the word "main"; it feels redundant. So the sentence would be:

"The purpose of this document is to describe the Solar Water Heating System software."

[danscime]

Sounds good to me!

[muhammadaliog3]

Describing the Issue:

1. The whole function located in Drasil/code/drasil-example/Drasil/SWHS/Body.hs:

purpDoc :: Sentence -> CI -> Sentence
purpDoc spSent pro = foldlSent [S "The main", phrase purpose, S "of this",
  phrase document, S "is to describe the modelling of" +:+.
  spSent, S "The", plural goalStmt `sAnd` plural thModel,
  S "used in the", short pro, S "code are provided, with an emphasis",
  S "on explicitly identifying", plural assumption `sAnd` S "unambiguous" +:+.
  plural definition, S "This", phrase document,
  S "is intended to be used as a", phrase reference,
  S "to provide ad hoc access to all", phrase information,
  S "necessary to understand and verify the" +:+. phrase model, S "The",
  short Doc.srs, S "is abstract because the", plural content, S "say what",
  phrase problem, S "is being solved, but do not say how to solve it"]

2. The function purpDoc is called once in entire module at about line 130 with

[IPurpose $ purpDoc (phrase swhsPCM) progName ...

3. The document currently prints: " The main purpose of this document is to describe the modelling of solar water heating systems incorporating PCM. "

Solving the Issue:
The part of interest:

purpDoc :: Sentence -> CI -> Sentence
purpDoc spSent pro = foldlSent [S "The main", phrase purpose, S "of this",
  phrase document, S "is to describe the modelling of" +:+.
  spSent, .............

This problem is fairly easy to fix, except for the spSent parameter, which at line 130 we know that spSent =phrase swhsPCM. phrase swhsPCM translates to "solar water heating systems incorporating PCM". So I changed line 130 by changing the spSent parameter to S "Solar Water Heating System". All the other changes are trivial.

So the part of interest becomes:

purpDoc :: Sentence -> CI -> Sentence
purpDoc spSent pro = foldlSent [S "The ", phrase purpose, S "of this",
  phrase document, S "is to describe the",
  spSent +:+. S "software", .......

The whole function becomes

purpDoc :: Sentence -> CI -> Sentence
purpDoc spSent pro = foldlSent [S "The ", phrase purpose, S "of this",
  phrase document, S "is to describe the",
  spSent +:+. S "software", S "The", plural goalStmt `sAnd` plural thModel,
  S "used in the", short pro, S "code are provided, with an emphasis",
  S "on explicitly identifying", plural assumption `sAnd` S "unambiguous" +:+.
  plural definition, S "This", phrase document,
  S "is intended to be used as a", phrase reference,
  S "to provide ad hoc access to all", phrase information,
  S "necessary to understand and verify the" +:+. phrase model, S "The",
  short Doc.srs, S "is abstract because the", plural content, S "say what",
  phrase problem, S "is being solved, but do not say how to solve it"]

While line 130 becomes:

[IPurpose $ purpDoc (S "Solar Water Heating System") progName ...

And the SWHS_SRS latex file shows "The purpose of this document is to describe the Solar Water Heating System software. " :).

I have pushed my changes up to my branch muhammad_data_table, you will see the only change I have made is to the Body.hs file. As soon as @smiths looks over my pull request this issue can be closed.

[JacquesCarette]

You have traced the symptom correctly.

However, I am less sure about the solution. What is the meaning of spSent? Where is it used? Normally, we want re-use, so if you change the 'name' in one place, it changes all over. We also don't want duplication - so if spSent is not re-used, then it contains duplicate information!

[muhammadaliog3]

spSent is just the placeholder name given to the first parameter, so it is locally defined.

For example, in the following code spSent plays the same role as num1.

add_two_num :: Int -> Int-> Int
add_two_num num1 num2 = num1+num2

However I did not change the name of spSent to something else, I changed the arguments with which purpDoc was called. The function purpDoc was originally called once with parameters (phrase swhsPCM) and progName, so I changed that to those parameters to (S "Solar Water Heating System") and progName. I hope that that clarifies any misunderstandings

[JacquesCarette]

See my comments on the actual code.

Your code is 'correct' (in the sense that the results print as wanted), but your fix is not, in that it is not the correct Drasil way to do things. The string "Solar Water Heating System" should occur only once in the whole codebase of SWHS.

[muhammadaliog3]

@JacquesCarette quick question. I wanted to know how I would access the ni field in the CI datatype (the second field)

import Control.Lens (makeLenses, (^.), view)
data CI = CI { _cid :: UID, _ni :: NP, _ab :: String, cdom' :: [UID]}
makeLenses ''CI

instance HasUID        CI where uid  = cid
instance NamedIdea     CI where term = ni
instance Idea          CI where getA = Just . view ab
instance CommonIdea    CI where abrv = view ab
instance ConceptDomain CI where cdom = cdom'
  

[JacquesCarette]

foo ^. term for the datatype foo. We don't want to access fields directly, we want to get to them through their "meaning", as given by the methods of the instance.

[muhammadaliog3]

Here are the changes I have made in my muhammad_swhs_edits branch, to actually understand them I recommend you go to the code itself.

1. All the information I need to print "The purpose of this document is to describe the Solar Water Heating System. " in the SRS is contained in the progName parameter, or the parameter with type CI. Hence the parameter with type Sentence is no longer needed. Also note that every drasil-example seems to have its own way of stating its purpose, except NoPCM, which will show in the other commit, so changing the parameter types of purpDoc will not have any other side influences.

2. The difficult part was getting "Solar Water Heating System". From progName I extract the named idea "solar water heating system" through pro ^. term. To capitalize on every word I had no option but to use the titleizeNP function in the NounPrase module. The other good thing about titleizeNP is that it returns a type sentence.

3. All the other changes are trivial, such as removing the word "main".

I have made a pull request @JacquesCarette