Updated Glassbr Introduction #2299

[NoahCardoso]

Closes #2299

The GlassBR SRS introduction reads poorly, so it would be nice to clean it up to read like a proper introduction. It assumes the reader already knows what the system is supposed to do / why it is there.

I made some improvements to the glassbr introduction from #2299

[smiths]

I know we don't have all the fields of information I mentioned when I proposed the introduction text, but I tried to use the Purpose that we already have (I believe) for GlassBR. Can we use the Purpose in the introduction? This would let us use the same text in multiple places. The purpose really should be the same everywhere it appears.

In re-reading my introduction text, I see that some of what I wrote was lost because I put it in angle brackets. I didn't really think about it, but now I think I was telling markdown that these were links. The text that didn't appear was the following proposed pattern for introductions:

[Motivation] [Purpose] [Examples] [Program Name]

I wrote the introduction for GlassBR using this pattern. At some point, we should look at all the examples to see if we can follow this pattern. We'll likely have to add some info fields, but it could be good, especially if we reuse that information. As I mentioned above, we should try to reuse the [Purpose] in the introduction. I believe all of our examples now have a [Purpose]. @NoahCardoso can you reuse the [Purpose] to generate the sentence in the introduction related to the purpose?

It is beyond the scope of this issue, but eventually I'd like to see us build the scope information as a related bundle of information. The scope is related to the scope decisions, assumptions, examples and typical values. These decisions are not made independently.

[NoahCardoso]

In re-reading my https://github.com/JacquesCarette/Drasil/issues/2299#issuecomment-2146534772, I see that some of what I wrote was lost because I put it in angle brackets. I didn't really think about it, but now I think I was telling markdown that these were links. The text that didn't appear was the following proposed pattern for introductions:

@smiths I am not really sure what you mean by this.

I know we don't have all the fields of information I mentioned when I https://github.com/JacquesCarette/Drasil/issues/2299#issuecomment-2146534772, but I tried to use the Purpose that we already have (I believe) for GlassBR. Can we use the Purpose in the introduction? This would let us use the same text in multiple places. The purpose really should be the same everywhere it appears.

In your comment, I believe the purpose statement is "Therefore, software is needed to predict whether a glass slab can withstand a blast under given conditions." I am not sure how this can be done by reusing the purpose text. Also I am not 100% sure what the purpose I am to reuse is.

When you mention to reuse the purpose are you referring to this?

[samm82]

@NoahCardoso You can find the "purpose" statement for GlassBR in the code permalinked below; hopefully it's trivial to reuse this in the introduction!

https://github.com/JacquesCarette/Drasil/blob/ef35006748d969442cdfaaf37f731d0d5f4e8bba/code/drasil-example/glassbr/lib/Drasil/GlassBR/Body.hs#L126-L128

(My approval is likewise a conditional one, based on this either being done, or an issue created for doing it in the future if it's not trivial.)

[smiths]

Thank you @samm82 that is exactly the purpose I was thinking about. @NoahCardoso hopefully it is relatively easy to reuse the existing purpose data.

[smiths]

The changes look good to me, as long as @samm82 is satisfied.