Drasil
Drasil copied to clipboard
JacquesCarette
Make Terminology and Definitions Sections Consistent
The Terminology and Definitions sections in all examples should follow the style of GamePhysics, SWHS, and NoPCM, and should be generated by docLang.
TODO
- [x] GamePhysics
- [ ] GlassBR (maybe after #1244)
- [ ] Redundant reference to References section
- [ ] Remove
termsDefnF' - [ ] Remove
[Contents]parameter
- [x] SSP
- [x] SWHS
- [x] NoPCM
- [x] Remove
noRefsLTfrom exports inutils - [ ] Sort list
(I think I'll use a similar workflow to #1403 - implement the desired result in Projectile and go back for the other examples later.)
I prefer bullet (or to use the 'definition' environments in latex/html). There is no point to numbered lists since the definitions will not be referenced that way.
This is of course another area where the docLang should be used to gain uniformity.
Since the Terms and Defs section is generated like so:
SSDProg [SSDSubVerb probDescription, ...]
Should this issue be expanded to generate the Problem Description section from docLang? It's a small(ish) section and shouldn't too difficult. @smiths @JacquesCarette
That sounds good to me, but @JacquesCarette will see the whole picture better than me. If this issue is expanded, please create another issue, rather than piggyback on this one.
In GlassBR, there are subsections like so:
If we wanted to automate this section, it would be a lot easier to collapse the list into one flat list. We would sort the whole list alphabetically (#1245), so it would still be easy to find a definition. The sub-definitions of glass type should be changed (ie. from "Annealed (AN)" to "Annealed (AN) glass").
What are your thoughts on this? @smiths @JacquesCarette
The definitions are currently subsections? I agree that having a list of definitions would be better. Numbering them isn't necessary, but sorting them alphabetically would be great.
The whole list is of type Contents, with the "subsections" (not literally subsections as in the docLang sense of the word) being generated like this:
termsAndDescBulletsGlTySubSec :: [ItemType]
termsAndDescBulletsGlTySubSec = [Nested (titleize glassTy :+: S ":") $
Bullet $ noRefs $ map tAndDWAcc glassTypes]
This is just way too complicated.
I believe I see what you are getting at now, and I don't think I like it. :-( Right now the definitions are grouped in categories. If they are listed in one flat list together the category information will no longer be apparent. I can see that you are proposing to keep it by adding a term to each term, but I don't think the information will be nearly as obvious.
There are two things we need to worry about:
- Capturing the knowledge, which includes the fact that there is a relationship between some of the definitions. That is, some of the definitions are in the same `category.'
- We need to display this information for humans. I think the knowledge capture and the display are too tied together.
I'm not sure we should prioritize this issue. I'd rather see us getting new things done than refining and iterating on what is currently displayed. I agree it should be fixed, but @szymczdm paper isn't going to be any stronger with a fix to how these text based definitions are displayed.
This issue is already marked as low priority. It might make sense for you to move to another tasks @samm82.
I'm just stuck waiting for PRs and looking for more stuff to do. What's the status of #1428?
I'm sorry that you are stuck @samm82. You'll just have to be a bit patient on #1428. I can't get to looking at it, because I tend to process my e-mails from the top down, and you keep putting new messages in my inbox. 😄 If you haven't read the papers that I suggested (Smith, Khedri and Lai), I suggest you spend some time having a look at those. 😄 If you haven't already done it, writing a Python program to do the projectile motion problem would be a good use of your time. There isn't anything wrong with faking a rational design process. :smile:
I already made code for Projectile (issue for code review is #1395), but I'll take a look at those papers (and I'll try to stop tagging you 😄).
Glad to hear that you have done the code already @samm82. You certainly are efficient. Don't worry about tagging me; it is my fault for working from the top of my stack down, but I just can't seem to break the habit. You'll just need to be a tiny bit patient. Fortunately it is almost the weekend. :smile:
So the comment https://github.com/JacquesCarette/Drasil/issues/1432#issuecomment-497816423 by @smiths is very important. And represents a real flaw in current Drasil: right now there is too much of a mix between presentation and information capture.
We need to capture the knowledge in 'clean' ways, first and foremost. And then we need to have that knowledge captured in such a way that we can write a "display recipe", hopefully in the docLang language, to display that nicely. We don't want to lose the 'nice display' either!
So your thinking for fixing these things should be:
- What information is really being captured in the 'display'?
- How is that information currently captured? [Semantically or just display-wise]?
- Is that method adequate for using it as 'knowledge'? Is that method adequate for printing?
- If the answer is 'no' to either parts of 3, figure out a better method. It will likely come in a pair, of a. upgrade the semantic capture b. add some nice printing for that
When you say https://github.com/JacquesCarette/Drasil/issues/1432#issuecomment-497811210 that 'it would be easier if...', that's always a red flag to me. You're letting ease-of-implementation dictate the design. What we need to be emphasizing is knowledge capture that is adequate. Printing nicely is almost always easy, once you have the 'right' data. The problem is thus in the data source, and that's where it should be fixed.
I'm taking a different approach for this issue now that should be better - should this list be labelled or not?
What if I were to define a type data Term = Sentence | SubTerm Sentence [Sentence]? Then we could pass a list of Terms to docLang for it to generate the list similiarly to the "manual" way we do it in GlassBR Body, except now it would be automated. Ideally we would pass terms (concepts) instead of Sentences, but #1244 makes this difficult. (I realize that this is similar to the "ease-of-implementation dictation", but I really don't know how to fix that and have tried since last summer. 😬) @JacquesCarette
That's still too display-oriented. I think the idea would be to maybe allow definitions to be nested, and that gets closer to the idea of what's going on (I think).
Another issue with GlassBR; it is the only example that also displays the acronym/symbol of the term. SWHS defines
Phase change material: A substance that uses phase changes (such as melting) to absorb or release large amounts of heat at a constant temperature.
without mentioning that the acronym is "PCM". Do we want the acronyms/symbols to be displayed? (I'm assuming yes, but this would also mean we are pretty much restricted to passing in [Sentence] (or an alternative for nesting definitions), since Drasil wouldn't be able to decide which function to use to extract the definition (and potentially acronym/symbol), so we would have to call it before passing the terms in.)
@JacquesCarette @smiths
Can you figure out the difference (in the code) that leads to this difference? I don't think there is any need to pass any more data, acronyms are information available from most chunks. I think it's just a rendering issue.
The terms and defs list isn't consistent, so each example generates the section in a different way. SWHS does:
termAndDefnBullets :: Contents
termAndDefnBullets = UlC $ ulcc $ Enumeration $ Bullet $ noRefs $ map tAndDMap
[CT.htFlux, phaseChangeMaterial, CT.heatCapSpec,
CT.thermalConduction, transient]
tAndDMap :: Concept c => c -> ItemType
tAndDMap c = Flat $ foldlSent [atStart c +: EmptyS, c ^. defn]
(ie. just pulls the term and definition from each item in the list)
GlassBR does:
termsAndDescBullets :: Contents
termsAndDescBullets = UlC $ ulcc $ Enumeration$
Numeric $
noRefs $ map tAndDOnly termsWithDefsOnly
++
termsAndDescBulletsGlTySubSec
++
termsAndDescBulletsLoadSubSec
++
map tAndDWAcc termsWithAccDefn
++
[tAndDWSym probBreak probBr]
(ie. uses a different function for displaying different items in the list, using tAndDOnly for terms without a symbol, tAndDWAcc for terms with an acronym, tAndDWSym for a term with a symbol defined in a separate quantity, and builds the subsections as follows)
termsAndDescBulletsGlTySubSec, termsAndDescBulletsLoadSubSec :: [ItemType]
termsAndDescBulletsGlTySubSec = [Nested (titleize glassTy :+: S ":") $
Bullet $ noRefs $ map tAndDWAcc glassTypes]
termsAndDescBulletsLoadSubSec = [Nested (atStart load `sDash` (load ^. defn)) $
Bullet $ noRefs $ map tAndDWAcc (take 2 loadTypes)
++
map tAndDOnly (drop 2 loadTypes)]
Thank you -- this is exactly what I was asking for you to dig up.
We should standardize this! @smiths , your turn!
I'm all for standardization, but I'm not sure what I'm being asked to do. GlassBR has "nested" or categorized definitions. If we are standardizing, then that is what we should standardize on. The other examples do not have categories, so they could be considered a subset of the behaviour in GlassBR.
To be honest, I don't think we should prioritize terminology. This is important, but I would much prefer the relationship between DDs, TMs etc converge clearly before we worry about something less "formal", like terminology.
Since the symbols are captured in the ToS, and the acronyms (except for LSF, which I will add) in the ToAaA, could we remove them from the Terms and Defs section(so only have the term and its definition)? My guess is no since we'd want to keep all information together, but this would also mean duplication of information.
We want each table to be readable on its own. And redundancy / duplication of information in user-facing documents is good.
I noticed this issue when updating the GlassBR example. It builds the Terminology and Definitions section with an independent termsAndDesc subsection instead of the standard TermsAndDefs constructor.
The original code for problem description is
PDProg :: Sentence -> [Section] -> [PDSub] -> ProblemDescription
but since we removed both the [Section] and [PDSub] to de-nested the section, I think we should build this section with the TermsAndDefs constructor like other examples.
Therefore, instead of SSDProblem $ PDProg prob [termsAndDesc],
it should be like TermsAndDefs Nothing terms.
This is the current definition of TermsAndDefs
data TermsAndDefs where
TDProg :: Concept c => Maybe Sentence -> [c] -> TermsAndDefs
If we would like to standardize and keep the categorized definitions, I think we have to change the Concept to Contents because we can't add other information with Concept type, or we could create a TermsAndDefs' for this kind of cases?
@tingyuw I just compared the generated "Terminology and Definitions" section for GlassBR to some of the other examples. The GlassBR one looks different, because it is an enumerated list, but it would be fine if the enumerated list is replaced by an itemized list. There might be a programming aspect I'm not aware of, but from the point of view of the generated documents, I don't have any problem with the requested change. There really isn't any reason for GlassBR to be treated differently for this section.
Despite it is an enumerated list, the way this section are built is also different from the others. The point might be whether we would like to keep the grouping of definitions by categories or list in one flat list like the other examples.
@tingyuw, I like the definitions grouped in categories. For instance, the glass types (annealed, fully tempered and heat strengthened) really should be grouped together. If they are separated in the list, it will be hard to see that they are all examples of glass types. Similarly, I like to see all the load types listed together. The load types (glass weight load, short duration load, specified design load, long duration load, non-factored load) fit under the Applied load title. It would be fine if Load Resistance was listed separately from Applied load, since Load Resistance isn't actually an applied load.
If you change GlassBR to match the other examples, do we lose the ability to group related definitions?
Yes, if we use the current constructor of TermsAndDefs, we can't add [Contents] (i.e., grouping definitions) for each concept. I believe a ConceptChunk only allows one sentence to define the concept. So it has to be a one flat list.
An alternative solution would be defining a TermsAndDefs' like
data TermsAndDefs' where
TDProg :: Maybe Sentence -> [Contents] -> TermsAndDefs`
for this kind of cases.
If @JacquesCarette is okay with your proposed implementation, I'd be fine with using this to add [Contents] to the terminology definitions.
Right, now I remember why GlassBR is different: the information to present in that section really is 'different', and organizing it the way it is leads to a better presentation.
What we really need are "organization schemes" for information. TermsAndDefs is good for capturing very precise semantics. Your TermsAndDefs' is closer, but it is designed in a little too haphazard a way (i.e. by making it fit the one example).
What's needed is a middle ground that sits between the high-level information and the low-level pure layout.
I'm not sure what the middle ground is supposed to be. TermsAndDefs doesn't support anything other than Concepts. If we are not making changes to the section definition itself, should we modify the definition of ConceptChunk to allow grouping definitions for each concept?
Hmm, I don't think changing ConceptChunk, at least for this purpose, is the right thing. This seems closer to a display issue, not a structuring one. One possibility is to have TermsAndDefs, for now, have 2 cases, which would let you punt the problem of designing a good solution to the future.