Drasil
Drasil copied to clipboard
JacquesCarette
Rework `Sentence`s to build them "properly"
In #3199 and #3237, the Sentences used for the new constructors were just done by wrapping the string with S. These now need to be reworked to use our concepts appropriately
Sure! For example, the following sentence (for its definition; S "the ratio ...") is simply a string wrapped in a Sentence constructor, but it should be built similarly to how other Sentences are built (for example, it should use the glass concept, shown below, using the phrase function). This ensures that we are using our concepts consistently and makes the document more maintainable.
https://github.com/JacquesCarette/Drasil/blob/24046be82e94e62acba7ccc73169c76a21de73b2/code/drasil-example/glassbr/lib/Drasil/GlassBR/Unitals.hs#L28-L30
https://github.com/JacquesCarette/Drasil/blob/24046be82e94e62acba7ccc73169c76a21de73b2/code/drasil-example/glassbr/lib/Drasil/GlassBR/Concepts.hs#L62
As for the specifics on how to build the sentences, there are numerous examples in the other examples of how to do this. The main ones I use are +:+ (for joining two Sentences with a space), :+: (for joining two Sentences without a space), +:+. (for joining two Sentences with a space and adding a period to the end), and foldSent and its variants, which converts a [Sentence] to a Sentence; this one uses +:+ between each Sentence and adds a trailing period.
@samm82 I see your meaning. So we need to use the given classes' functions to define strings, not just directly use S "...". However, what is the range of my changes? I see the String S... occurs a lot of places, including websites and different examples.
Do I only need to change the
glassbr example, or all examples? Do I need to change String examples in the website code?
@JacquesCarette Before I have already created a branch to include glassbr changes (not all changes), since its volume is heavy. Like other issues, I think I have been very closed to the solution. (Have not been submitted)
@daijingz Using S "..." is sometimes fine/necessary, but as much as possible, we should use pre-existing combinators (like +:+) and "concepts" (like plural quantity). This should be done as much as possible throughout the examples (and probably the website code as well). My guess is that this issue is really one that will be iterative (e.g., it will never quite be "done"), so just do as much as you can!
@daijingz Using
S "..."is sometimes fine/necessary, but as much as possible, we should use pre-existing combinators (like+:+) and "concepts" (likeplural quantity). This should be done as much as possible throughout the examples (and probably the website code as well). My guess is that this issue is really one that will be iterative (e.g., it will never quite be "done"), so just do as much as you can!
@samm82 I guess in the previous example, S "the ratio of tensile stress to tensile strain of glass" should be:
nc "the ratio of tensile stress to tensile strain of glass" (nounPhraseSP "the ratio of tensile stress to tensile strain of glass")
I feel a little bit strange, because this is already done, and there is no need to use combinators. (Maybe I have misunderstanding)
Because this issue may have some obscure requirements here, to get success, let me submit my previous example (incomplete, just a few modifications on several examples) today, so that you can find where I have the inconsistency from the expectation.
Up to now, my understanding of the code range: All Drasil examples and the Drasil website. I am checking code examples. My plan is to define the website first, then detail each example.
I feel the Drasil website does not have new definitions (concepts), so it must use S "". I see the whole website code, which does not include any new definitions of plural quantity. Does this mean we do not need to change S "" in the Drasil website? (I guess changing the Drasil website is unnecessary)
I guess in the previous example,
S "the ratio of tensile stress to tensile strain of glass"should be: nc "the ratio of tensile stress to tensile strain of glass" (nounPhraseSP "the ratio of tensile stress to tensile strain of glass")
We should not do this: what we would want is to split S "the ratio of tensile stress to tensile strain of glass" into something like S "the" +:+ phrase ratio `of` phrase tensileStress +:+ S "to" phrase tensileStrain `of` phrase glass; this may mean some terms may need to be added; look in drasil-data both to see what terms we have available and how they are defined to be used in other examples in case you need/want to add more.
@samm82 There is a question: what kind of or what length of Sentence should be split? I guess a single-word sentence will be inappropriate for further splitting (no space).
Two expected tools: foldLlist and phrase
I guess here is a good example:
secondPendDesc:: Sentence
secondPendDesc = foldlSent[
atStartNP (the secondRod) +:+. S "has two sides",
S "One side attaches" `S.toThe` (phrase firstObject !.),
S "Another side attaches" `S.toThe` phrase secondObject]
I can't find secondPendDesc in the linked PR that this issue seeks to refactor; are you sure you are commenting on the correct issue/looking in the correct place?
Before I believed that all phrase related definitions should be used. My mistake, let me search this def.
Assumption 1: Only use the phrase definition.
Assumption 2: This issue's scope is inside this path: Drasil\code\drasil-example. (Inside these examples, such as hghc)
@samm82 Is this correct? I think my location is not wrong.
Example: D:\Drasil\code\drasil-example\dblpend\lib\Drasil\DblPend\Assumptions.hs
There will likely be some other functions you'll need to use; for example, plural if the term should be pluralized. Since we have a lot of functions for building Sentences from concepts, you can do as much or as little as you can. Honestly, the smaller the PR the better, so that's it's easier to review and so that, say, 9 good changes get held up from being merged because of 1 change that needs more work.
You can start with the examples folder, but there will likely be some other places that can use work (e.g., some parts of Drasil responsible for building sections of the document). If you can't find them, don't worry about it! Again, smaller PRs are better.
When I said "are you sure you are commenting on the correct issue/looking in the correct place", I seem to remember a PR being referenced that didn't match up with the comment you made on this issue, which confused me. The example you mentioned looks good to me! You can potentially define a new concept for "side" and use that, as well as in other places it is used, but it is up to you whether or not you do it (you may also want to justify the concepts you pull out, since it won't be worth doing the work for some of them, but others it could be quite useful!)
I guess here are all the definitions you want to have:
D:\Drasil\code\drasil-lang\lib\Language\Drasil\Development\Sentence.hs
Starting from Phrase
I guess these sentences do not need to change.
I found three reuseable sentence patterns: S.toThe, S.is, and S.isThe