Drasil: Convenience combinators in `Chunk.NamedIdea` - understand the use

[JacquesCarette]

Starting around line 66, there are a whole lot of combinators that really don't belong here. If nothing else, all the ones which produce Sentences or NP (from line 66 onwards) should be moved out. They are not necessarily bad, but we need to understand them better. They are too based on English and not enough on semantic content.

Take one example: the on line 190. Does it really make sense to have this NamedChunk-producing thing? The UID manipulation is kind of horrific. Why is it needed? How is it used? Does it make sense?

Other examples are subtly different. Some of the of and for combinators probably are expressing something "meaningful". But which? We don't want to just eliminate these, as some really do encompass some 'knowledge capture'.

I think the first thing to do is to see how/where they are used. @niazim3 could you do this? For combinators that are used < 5 times, it probably makes sense to show their usage as comments. For those used >= 5 times, some kind of summary information would be good. Then we can decide, possibly combinator-by-combinator, what to do with them. And that later task will be distributed amongst many more people.

[JacquesCarette]

Making sure that @smiths and @szymczdm see this issue. I think it is going to lead us towards a bunch of mini-projects for the next week(s). Especially the more semantically meaningful parts.

[niazim3]

WIP (Question: is a notification sent to everyone associated with this issue every time a comment is edited? If that's the case, I can keep track of the summary and found instances elsewhere and transfer them all to this issue upon completion... @JacquesCarette )

Summary of combinators line 66 (compoundNC' onwards):

Found <5 times :

1. compoundNC' : used 2x in _Documentation.hs_; combines 2 pluralized NamedChunks input into a single NamedChunk
2. compoundNC'' : used 4x times in _Computation.hs_; combines 2 NamedChunks input into a single NamedChunk depending on the input function types (i.e. NP.plural, NP.phrase)
3. compoundNC''' : used 1x in _Documentation.hs_; hack for solutionCharSpec
4. for : used 4x in 4 different files; inserts the word "for" between the titleized versions of two terms
5. for' : used 1x in _Body.hs_ of GamePhysics
6. for'' : used 2x in _SRS.hs_ in building forTT and forTT' (non-exported local functions); takes in 2 functions as input to apply to Sentence inputs
7. of_' : used 2x in _Documenatation.hs_; same as of_, except phrase default of second term is plural instead of phrase
8. of_'' : used 1x in SSP\Defs.hs; same as of_, except plural default of second term is phrase
9. of__ : used 1x in Documentation.hs; same as of_, except phrase default of first term is plural instead of phrase
10. with' : 1x in SWHS/Concepts.hs;
11. and_ : 1x in Documentation.hs;
12. and_': 1x in Documentation.hs;
13. andRT: 1x in Documentation.hs;
14. theCustom: 1x in Documentation.hs;
    15: ofA: 1x in Documentation.hs;

Found >= 5 times:

1. of_ : Creates a noun phrase by combining two NamedIdeas with the word "of" between their terms.
2. the: (NamedIdea c) => c -> NamedChunk by attaching 'the' to 'c'

(Edit) Removed items:
of'' : 0x (not used anywhere); but functions for both terms (that are also passed in) are applied to construct a Sentence
with : 0x (not used anywhere); description needs to be updated as there is no of' that is mentioned
a_: 0x (not used anywhere)
this: 0x (not used anywhere)
aNP: 0x (not used anywhere)

[JacquesCarette]

To all the 'participants', but not to people who have just been tagged. Go ahead and work here - we can all set up filters so that these notifies go to sub-folders.

[JacquesCarette]

@niazim3 Is this done then? [I mean, the 'analysis' phase]?

[JacquesCarette]

If with is not used, please delete it.

[niazim3]

Removed combinators that were not used in the files for this repo (with, aNP, this, a_, and of''). Analysis phase complete.

[JacquesCarette]

So now we need to understand more deeply what each of these is "trying to say". So I think all the ones which produce NP should be split out. Probably into a new Data.Drasil.Phrase.hs file. They do make things in Data.Drasil.Concepts.Documentation look nice, so they are worth keeping.

[smiths]

@JacquesCarette, are you asking @niazim3 to make the change of splitting NP out?

[JacquesCarette]

No, of taking the combinators in the Chunk.NamedIdea files that produce NP out of that file (and out of the Language.Drasil hierarchy) into something in Data.Drasil.

[niazim3]

I was working on transferring the combinators over to the file added in the commit mentioned above, when I ran into the following error:
``C:\Users\Owner\literate-scientific-software\code\Data\Drasil\Phrase.hs:9:5: error: * Could not deduce (NamedIdea NP) arising from a use ofphrase'
from the context: (NamedIdea c, NamedIdea d)
bound by the type signature for:
of_'' :: (NamedIdea c, NamedIdea d) => c -> d -> NP
at Data\Drasil\Phrase.hs:7:1-51
* In the first argument of (+:+)', namely(phrase $ t1 ^. term)'
In the first argument of (+:+)', namely (phrase $ t1 ^. term) +:+ S "of"'
In the first argument of nounPhrase'', namely
`((phrase $ t1 ^. term) +:+ S "of" +:+ (phrase $ t2 ^. term))'

-- While building package drasil-0.0.9 using:
C:\sr\setup-exe-cache\x86_64-windows\Cabal-simple_Z6RU0evB_1.24.2.0_ghc-8.0.2.exe --builddir=.stack-work\dist\ca59d0ab build lib:drasil exe:chipmunkdocs exe:glassbr exe:nopcm exe:ssp exe:swhs exe:tiny --ghc-options " -ddump-hi -ddump-to-file"
Process exited with code: ExitFailure 1
make: * [build] Error 1
```

After looking into what is usually the cause for such an error, it seeems the type signature needs to follow the current type signature. Can I get some suggestions on how to fix this issue? (I've already tried removing the type signature completely)

[JacquesCarette]

The problem is sneaky: there is a phrase function exported by Language.Drasil which does
phrase (x ^. term)
and so in your of_'' implementation, that's the one you are picking up instead of the one from NounPhrase.

[niazim3]

Completed transferring combinators into Data.Drasil.Phrase from Language.Drasil.Chunk.NamedIdea ^.

[JacquesCarette]

We now need to understand which ones are left. Can you post a list?

[niazim3]

Combinators left in Language.Drasil.Chunk.NamedIdea:

1. compoundterm :: (NamedIdea c, NamedIdea d) => c -> d -> NamedChunk is a combinator for combining two 'NamedIdea's into one NamedChunk. (NOTE: function has the same definition as 2, so is this even needed?) (removed in commit 2428e13)

1. compoundNC :: (NamedIdea a, NamedIdea b) => a -> b -> NamedChunk is a combinator for combining two 'NamedChunk's into one.
2. compoundNC' :: (NamedIdea a, NamedIdea b) => a -> b -> NamedChunk is a combinator for combining two 'NamedChunk's into one after pluralizing them.
3. compoundNC'' :: (NamedIdea a, NamedIdea b) => (NP -> Sentence) -> (NP -> Sentence) -> a -> b -> NamedChunk is a combinator for combining two 'NamedChunk's into one by also taking into account the functions that should be used on them (i.e. plural, phrase, etc.).
4. compoundNC''' :: (NamedIdea a, NamedIdea b) => (NP -> Sentence) -> a -> b -> NamedChunk is a hack for "Solution Characteristics Specification", should most likely be removed.
5. for :: (NamedIdea c, NamedIdea d) => c -> d -> Sentence inserts the word "for" between the titleized versions of two terms.
6. for' :: (NamedIdea c, Idea d) => c -> d -> Sentence is similar to for, but uses titleized version of term 1 with the abbreviation (if it exists, phrase otherwise) for term 2.
7. for'' :: (NamedIdea c, NamedIdea d) => (c -> Sentence) -> (d -> Sentence) -> c -> d -> Sentence is similar to for, but allows one to specify the function to use on each term before inserting for.
8. the :: (NamedIdea c) => c -> NamedChunk attaches the to 'c'.
9. theCustom :: (NamedIdea c) => (c -> Sentence) -> c -> NamedChunk is similar to the, but allows one to specify the function to use on the term before inserting "the".

[JacquesCarette]

6,7,8 are kind-of ok. They can be moved to Data.Drasil.Phrase. We can re-examine them later. I think they do embody a deeper idea, at least in some cases.

So let's understand the and theCustom. I understand what they do, what I need is all the places where it is used. At this point, the actual line of code of each use. In part, I want to understand what NamedChunk they really produce. Also, figuring out where those produced NamedChunks are then further used would be useful, to provide the fully context.

I simply have no idea whether the feature this provides is useful or an awful hack or somewhere in between.

[niazim3]

the:

• used to create theCustomer (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/SRS.hs#L44) which is used in Stakeholders.hs to create tCustomerF (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/Sections/Stakeholders.hs#L33)
• used to create theClient (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/SRS.hs#L45) which is used in Stakeholders.hs to create tClientF(https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/Sections/Stakeholders.hs#L24)

both of the above created functions (tClientF and tCustomerF) are then used to produce a section using mkStkhldrSec(https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/DocumentLanguage.hs#L366-L374)

• produce "the product" in Stakeholders section (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/Sections/Stakeholders.hs#L21)
• produce "The client" in Stakeholders section (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/Sections/Stakeholders.hs#L27) and (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/Sections/Stakeholders.hs#L29)
• produce "The customers" in Stakeholders section (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/Sections/Stakeholders.hs#L36)
• produce "The data definitions" under the Organization of Document section for GlassBR (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/GlassBR/Body.hs#L313)
• produce "The physical system" under the Physical System Description section of GlassBR (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/GlassBR/Body.hs#L414)

theCustom:

Is used in Documentation.hs (https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Data/Drasil/Concepts/Documentation.hs#L214-L215), which is used to produce the scpOfTheProj NamedChunk, which is then used to produce the following outputs for the examples:

• "This section presents the scope of the project." resulting from this definition from ScopeOfTheProject.hs:(https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/Sections/ScopeOfTheProject.hs#L16)
• "Scope of the Project" heading resulting from this definition from SRS.hs:(https://github.com/JacquesCarette/Drasil/blob/cad5e614b0cfa68ce05f69ef7944bdfa53df77a6/code/Example/Drasil/SRS.hs#L52)

[niazim3]

Is there a way to understand whether the thes are capturing just English or some meaning at this point that I can contribute to?

[JacquesCarette]

I will point out that none of these are left Chunk.NamedIdea. Many (most, all) are in Data.Drasil.Phrase now. So I'm closing this.