Drasil icon indicating copy to clipboard operation
Drasil copied to clipboard

remove the definitions of `acronyms` from all the examples in drasil-examples

Open JacquesCarette opened this issue 1 year ago • 5 comments

Note: this will most likely not be straightforward. Some of the things in acronyms are likely redundant, others will belong elsewhere while others still will be related to infrastructure and should be inserted in the various databases via other means. I definitely expect a number of side-issues to get spawned off of this work.

JacquesCarette avatar Jul 14 '23 20:07 JacquesCarette

I think there's a relatively smooth way to go about doing this, starting by removing the common acronyms in each of the case studies:

  1. Look at each of the Concepts.hs files in the case study code folders.
  2. Analyze which chunks are shared across them all (or at least shared across $n > 1$).
  3. In drasil-data, create a new file called CommonChunks.hs and create a basic ChunkDB in it containing all earlier found, shared acronyms (which should all originate from drasil-data, anyway).
  4. In drasil-database, create a function that extends a ChunkDB, likely using a similar signature to the existing cdb smart constructor, except with a source ChunkDB that it extends. This particular step is suboptimal, but that's okay -- it's out of scope.
  5. In each of the case studies, replace the code that creates a new ChunkDB (this will commonly be found by a cdb use in Body.hs) with code that uses your new commonChunkDB (from drasil-data/step 3) and extends it with the chunks created for each of the respective case studies.
  6. At this point, you should be able to test if the code still regenerates the same stable/ artifacts -- don't be surprised if it fails, that's okay. Those changes will likely spawn new side-issues as mentioned in the OP.
  7. For all the chunks that weren't added into commonChunkDB, try to explain why it was inappropriate to add them.

balacij avatar Feb 13 '24 23:02 balacij

Ah, it looks like #3347 already discusses a problem that would be found in step 6 above. That's okay though, we can have a WIP PR.

balacij avatar Feb 14 '24 02:02 balacij

Operationally, your steps make sense. What's missing is that in step 3, there should some kind of "semantic analysis" pass to try to make sense of what that duplication actually is / means. Often, the result should not go into some CommonChunk.hs (which is no different than calling it Misc.hs) but rather into a "proper home".

Step 7 is wonderful.

JacquesCarette avatar Feb 16 '24 17:02 JacquesCarette

  1. In drasil-data, create a new file called CommonChunks.hs and create a basic ChunkDB in it containing all earlier found, shared acronyms (which should all originate from drasil-data, anyway).

For step 3 how would you go about creating a basic ChunkDB? What needs to be included from ChunkDB? Also for the acronyms that are not shared should they still be removed?

NoahCardoso avatar May 28 '24 15:05 NoahCardoso

Familiarizing yourself with ChunkDB.hs from drasil-data should be helpful for (3) & (4), there's a smart constructor in that file that you can use to create a basic ChunkDB. Regarding your other two questions, you'll have to figure them out slowly. It would be good to start with the acronyms that you think should be shared first, and then we can go from there.

Regarding the locale, it might actually be more appropriate to create the CommonChunks.hs file in drasil-docLang since acronyms contain SRS-specific concepts such as TMs (TheoryModels) and the likes, but we can confirm that later.

balacij avatar May 28 '24 23:05 balacij