Descriptive text for Description field

[smiths]

@JacquesCarette, my understanding is that Drasil now completely automates building the "Description" field for the TMs, IMs, DDs etc. I believe that a new field was created for the descriptive text that used to be part of the descriptions in the case study. Is this correct? What is this new field called? Notes? As I am working on the transition between the manual case studies and the documents that Drasil generates I find that I need a place to put this "extra" information. I would like to use the proper terminology so that I can explain to others what I think we should do with the case study content. This has come up implicitly in a few issues, but I'm not actually sure about the current status of our code base with respect to the "freeform" description text.

[JacquesCarette]

We do call it Notes, yes. Internally, there is a HasAdditionalNotes class with a getNotes method. I just double-checked that the 4 items (TM, IM, DD, GD) all have a notes field.

I'm not sure if that's all the information that was needed for this question/issue, so I won't close it yet.

[smiths]

Great. This is very helpful. I think that is all I need to know, but just to be certain, let me pull an example from the SWHS case study:

Moving forward, we would have the Description field list each symbol, its meaning and units. All of this would be generated. The sentence that starts "The above equation applies ..." would be moved to the notes field.

Although it wasn't part of my original question, something else occurs to me while reading this example. My understanding is that the equations for tau_W and eta that appear in the manual case study wouldn't currently appear in the Drasil version. Right? I believe this is why I created DDs for tau_W and eta (looks like I forgot to reference the DD for eta; I'll add that in the manual repo.) In the

Drasil code, we can have references to other chunks, like data definitions, in the Description field, or does this information also have to go in the Notes field?

[JacquesCarette]

Re 'Moving forward' para: correct.

I believe you are correct, those equations for tau_W and eta would not appear, though the DDs could be referenced. At least, if that's not currently possible, it should be. In fact, it could be a feature request to have the equation show up, but that would have to be some kind of explicit "instruction" that would have to be attached to the rendering of that particular item.

[smiths]

This discussion reminded me of some other discussions, so I thought I should search through our issues and make some connections. The Notes field is discussed in at least two other issues: #522 #751. The notes field is available, which is great, but I don't think it has been used to get the Drasil versions to match the manual versions. If it has, then there are some issues related to missing information between the two that we can close.

We have discussed including equations in the description of symbols in a data definition as part of the SWHS repo.

smiths/swhs#35

The problem appears to be that defining the symbols in the equation will require some kind of recursion, especially if the symbols are themselves described by equations. 😄 I remember the conversation now. I believe our conclusion was to postpone this headache and simply define the symbols in their own Data Definitions. There really isn't any harm in this. From a knowledge point of view they are separate chunks of knowledge. We've only looking at short cuts in displaying the information because that was what was done in the manual version. Since we can reference DDs from within the description, the equation is available to the reader by following the link.

My original question was answered, so I will close this issue now.

[JacquesCarette]

Some of the missing information has come back through the notes - not sure if all of it did.