Evaluate (Seemingly Outdated) DocLang Constructors.

[Mornix]

DocLang is (moreso in the past) a living structure that has evolved over the course of its life. As such, likely some of the constructors are outdated and unused, but have been forgotten about.

For example: GSDProg, no examples use this constructor, and it's types look like it was an older version from when Drasil was much more layout oriented. Further evidence of this is the next constructor for GSDSec: GSDProg2.

I'm sure there are others in DocLang which have become forgotten about and superseded.

If you're looking for something to do, can you catalogue the unused DocLang constructors? I don't want to remove them just yet as @JacquesCarette might have some insight on why some haven't been removed, but I definitely think some could be.

[samm82]

A summary of observations:

1. TUnits' is never used (should it be? It has a comment -- Customized intro, which mean we might want it later?)
2. TSymb (and TSymb') are never used directly - they are called by the functions tsymb, tsymb', and tsymb''. Is this desired?
   

   Drasil/code/drasil-docLang/Drasil/DocumentLanguage.hs

   Lines 293 to 304 in 76913ec

   	-- | table of symbols constructor
   	tsymb, tsymb' :: [TSIntro] -> RefTab
   	tsymb = TSymb
   	-- ^ Default Term and given intro
   	tsymb' = TSymb' Defn
   	-- ^ Default Defn and given intro
   	-- | Custom table of symbols constructor
   	tsymb'' :: [TSIntro] -> LFunc -> RefTab
   	tsymb'' intro lfunc = TSymb' lfunc intro
   	-- ^ Custom function and intro.

3. Related to #3 - tsymb' is never used and could be removed?
4. Since we sort the table of symbols alphabetically, SymbOrder shouldn't be an option to be passed in. We should always mention that the ToS is alphabetical.
5. I also think we should always include the purpose of the Table of Symbols (TSPurpose)
6. StkhldrProg is never used and should be removed, and StkhldrProg2 should be renamed to StkhldrProg (Minor Naming Fixes in docLang #1846)
7. We could look into automating SysCntxt, UsrChars, and SystCons
8. GSDProg is never used and should be removed, and GSDProg2 should be renamed to GSDProg (Minor Naming Fixes in docLang #1846)
9. As mentioned in Off the Shelf Solutions Section Name #1458, all instances of "Existing Solutions" should be replaced with "Off The Shelf Solutions"

[samm82]

Also, it was mentioned previously that we were moving away from labels. What should be done with the docLang labels?

[smiths]

The observations listed above will be helpful in planning modifications to Drasil. I'm sure @JacquesCarette will have some advice based on this. Hopefully there will be some code cleanup that this facilitates. One thing that I don't think we should change is your observation 4, where you observe that we always sort the table alphabetically. Although that is true for the current set of examples, we want our documentation "recipes" to allow for a family of documents that may be quite different from our current examples. In the future, someone may have a recipe where the table of symbols is presented in order of appearance. It is also conceivable to have different versions of what it means to sort alphabetically. We had to make decisions on how to handle Greek characters, subscripts and supercripts. Someone else might want to make different choices. If it doesn't cause us any problems, we should keep our interface as general as we can.

[JacquesCarette]

I need to dig deeper into this. Most likely I agree with all of the above, but without looking at the code itself, I might forget something important.

[Awurama-N]

I searched through Drasil example for all the constructors mentioned in DocLang, Here are the results:

I found no instances of the following constructors in any of the drasil examples:

• ddefn
• inTable
• ddRefDB
• termDefnF'
• getDocDesc
• egetDocDesc
• ciGetDocDesc
• generateTraceMap
• as for tunit i found instances of TUnits but none of tunit or tunit'

@JacquesCarette

[JacquesCarette]

Excellent. I would say that the task on this issue is almost done. What you should do next is to create one issue each for all 9 (10?) of the above constructors, to investigate removing them. The first step, for each, would be an investigation of

1. what is that constructor supposed to be building (or returning)
2. what other constructors are there that also build that
3. are there parts of the data-structures that would become redundant because all of its constructors would disappear?
4. perhaps an initial hands-on investigation that removes it, to see if it truly is not used

For some of them, perhaps 1 will reveal that we really do want to do that, it's just not plugged in yet. So the 'solution' will be to plug it in, not to delete it!

[Awurama-N]

I started the investigation and just put 5 tickets up assigned to myself, but i was wondering if maybe they might be too vague? i thought it wouldn't matter because it's assigned to myself, but maybe for future purposes and clarity should i add some more detail? @JacquesCarette

[JacquesCarette]

They are indeed too succinct. At the very least, they should all refer to this issue, which does have more context. In the future, we might indeed need to look at them again, and then they wouldn't make any sense "on their own", even if they were all fixed.