Drasil: Create drasil-utils SubPackage

[samm82]

As per comments on #1388, there should be a drasil-utils. The file structure will be:

+ Utils.Drasil
| --- Fold.hs (contains folde, foldlList, foldlSent_, etc. from SentenceStructures)
| --- Misc.hs (everything else until we re-allocate them)
| --- Phrase.hs (phrase builders)
| --- Sentence.hs (sentence constructors like sAnd, ofThe, etc. from SentenceStructures)

TODO

• [x] Move marked functions from SentenceStructures.hs to Utils.hs (#1411)
• [x] Make Sentence in utils (#1436)
• [x] Move Phrase to utils (#1470)
• [x] Make Fold in utils (SentenceStructures) (#1448)
• [x] Make Misc in utils (Utils) (#1510)
• [x] Move rest of SentenceStructures to Misc (#1544)
• [x] printers should depend on utils now, not data (#1448)
• [x] Update Wiki

[JacquesCarette]

If it is going to be mostly filled with utilities to deal with Sentences, it's tempting to call it drasil-english. If it's a mixture of generic Haskell code and other things, -utils is probably right.

And yes, many of the things in SentenceStructures.hs are not really in the right place.

[samm82]

Most functions create a Sentence; the only exceptions are figureLabel that creates a LabelledContent (marked with a FIXME wondering if it's in the right file) and the term formatters that return an ItemType (tAndDWAcc, tAndDWSym and tAndDOnly).

There is also a section of functions at the bottom marked "TO BE MOVED TO EXAMPLE/DRASIL/SECTIONS", which is now docLang, so I'll move those to there.

[JacquesCarette]

The stuff that generates pieces of documents should all go into docLang for now.

[samm82]

There already exists a Data.Drasil.Utils. Should this, and Data.Drasil.SentenceStructures (once all functions unrelated to Sentences are removed) both be moved to drasil-utils? I think it makes sense for some stuff from SentenceStructures to be in Utils, just not sure in which package things should go (ie. if we're going with a drasil-english package).

[samm82]

Also, instead of moving these functions to docLang, I'm moving them to Utils.hs, since they have potential to easily be reused at some point in the future. (If that's OK with you @JacquesCarette)

[samm82]

@JacquesCarette Can you review my changes in the utils branch and see if you like the direction I went with it?

[JacquesCarette]

I looked - it seemed fine. This is an incremental process, as we learn, we'll figure out where the best home for various things is.

[samm82]

Would a good file structure be something like

+ Utils.Drasil
| --- Utils.hs
| --- SentenceStructures.hs

with everything exported in Utils.Drasil? @JacquesCarette

[samm82]

@JacquesCarette It also looks like Data.Drasil.Phrase contains a lot of functions that could also be migrated.

[samm82]

I think I'm going to go ahead on this:

+ Utils.Drasil
| --- Fold.hs (contains folde, foldlList, foldlSent_, etc. from SentenceStructures)
| --- Misc.hs (everything else until we re-allocate them)
| --- Phrase.hs (phrase builders)
| --- Sentence.hs (sentence constructors like sAnd, ofThe, etc. from SentenceStructures)

[JacquesCarette]

I concur, that is a good arrangement. And yes to moving other items like you have.

[samm82]

@JacquesCarette Some notes about removing imports from Utils.hs because they cause issues:
~1) fterms is just imported from Data.Drasil.Concepts.Documentation, not used, and then exported. Is there a design decision behind this or can I remove it from the import list?~

EDIT: I found a -- FIXME: fterms is here instead of Utils because of cyclic import, but the cyclic import will be resolved with the resolution of these issues.
2) prodUCTbl is never used in Drasil:
https://github.com/JacquesCarette/Drasil/blob/6e7a37d90e34355a21a7569066e56c490db01e22/code/drasil-data/Data/Drasil/Utils.hs#L183-L186
Should it be removed? Further investigation shows that the use case table has been completely removed from all examples (I even used to have an issue about the one in GlassBR - #833), and I can't find an issue for it. Was this intentional?
3) The separate issue #1440 should also be addressed before proceeding on this one.

EDIT: Also, does it make sense for utils to depend on data or vice versa? The code right now could go either way, but I think it makes sense to have utils be close to lang, and anything that needs data should probably be moved to docLang.

[smiths]

Yes, prodUCTbl should be removed. In the revisions that @vajihehm and I did to GlassBR we removed it. It was a mistake to have use cases in the GlassBR documentation. It was worth exploring, but it doesn't add anything to the documentation, at least not in any of our examples. There is one use case for all of our examples: input data, calculate results, output results. This use case is explicit in our documentation through the requirements. It would be redundant to say it again.

[JacquesCarette]

Go ahead and move fterms. Hopefully #1440 is easy.
In our current vision of things, utils should not depend on data as packages. Do note that drasil-lang contains part of the Data.Drasil hierarchy (by design), which is slightly different.