Lacking Clarity (and Consistency): Table of Symbols Constructors

[Mornix]

Table of Symbols Constructors are in an odd place.

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

Lines 78 to 83 in f43b3c1

	data RefTab where
	TUnits :: RefTab
	TUnits' :: [TUIntro] -> RefTab -- Customized intro
	TSymb :: [TSIntro] -> RefTab
	TSymb' :: LFunc -> [TSIntro] -> RefTab
	TAandA :: RefTab

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

Lines 119 to 124 in f43b3c1

	data LFunc where
	Term :: LFunc
	Defn :: LFunc
	TermExcept :: [DefinedQuantityDict] -> LFunc
	DefnExcept :: [DefinedQuantityDict] -> LFunc
	TAD :: LFunc --Term and Definition

The Constructors seem fairly logical. A simple constructor, and a more customizable one. While this is something that could benefit from a smart constructor, it isn't something of super high priority.

If we look at what the constructors do to create the table of symbols, the lack of clarity (should) become[s] clear.

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

Lines 267 to 274 in f43b3c1

	mkSubRef SI {_quants = v} (TSymb con) =
	SRS.tOfSymb
	[tsIntro con,
	LlC $ table Equational (sortBySymbol
	$ filter (`hasStageSymbol` Equational)
	(nub v))
	atStart] []
	mkSubRef SI {_concepts = cccs} (TSymb' f con) = mkTSymb cccs f con

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

Lines 279 to 293 in f43b3c1

	mkTSymb :: (Quantity e, Concept e, Eq e, MayHaveUnit e) =>
	[e] -> LFunc -> [TSIntro] -> Section
	mkTSymb v f c = SRS.tOfSymb [tsIntro c,
	LlC $ table Equational
	(sortBy (compsy `on` eqSymb) $ filter (`hasStageSymbol` Equational) (nub v))
	(lf f)]
	[]
	where lf Term = atStart
	lf Defn = (^. defn)
	lf (TermExcept cs) = \x -> if (x ^. uid) `elem` map (^. uid) cs then
	x ^. defn else atStart x --Compare chunk uids, since we don't
	--actually care about the chunks themselves in LFunc.
	lf (DefnExcept cs) = \x -> if (x ^. uid) `elem` map (^.uid) cs then
	atStart x else x ^. defn
	lf TAD = \tDef -> titleize tDef :+: S ":" +:+ (tDef ^. defn)

Drasil/code/drasil-database/Database/Drasil/SystemInformation.hs

Lines 23 to 31 in f43b3c1

	SI :: (CommonIdea a, Idea a, Idea b, HasName c,
	Quantity e, Eq e, MayHaveUnit e, Quantity f, MayHaveUnit f, Concept f, Eq f,
	Quantity h, MayHaveUnit h, Quantity i, MayHaveUnit i,
	HasUID j, Constrained j) =>
	{ _sys :: a
	, _kind :: b
	, _authors :: [c]
	, _quants :: [e]
	, _concepts :: [f]

A TSymb constructor takes all members of the _quant field to print. This can be something such as a [QuantityDict] or [DefinedQuantityDict]. Nothing too wrong with this constructor, although it could be a great candidate for automation.

Looking that the other constructor, TSymb' (and related function -- mkTSymb), we can see that an additional constraint is required: Concept. As a result of this, the _quants field is not pulled as it doesn't contain the Concept constraint, instead the _concepts field of SystemInformation is used. With this being the case, we cannot enumerate symbols which are missing a Concept. This alienates QuantityDict, UnitaryChunk (which GlassBR makes heavy use of), among others. The upside is, with the TSymb' constructor, symbols are pulled automatically from the document.

This restriction seems a (little) arbitrary and hacky, especially if LFunc is Term. We are left with some symbols (possibly) being excluded. Moreover, it seems odd that if we want to describe the term of a symbol we can get "all" symbols, whereas when we describe defn we may only display a subset.

TL;DR: Is it intentional that TSymb' takes a subset of all symbols and thus a Table of Symbols would be "incomplete"?

[JacquesCarette]

I would be very surprised if this was intentional. [Well spotted BTW]. This likely evolved organically, and some of the divergence happened "to make things work".

This Quantity vs Quantity+Concept thing has happened multiple times already. I wonder how many Quantities that aren't Concept we actually have.

[samm82]

Just a note that the quantPlate branch still needs some work and should be considered while working on this issue.