search

JacquesCarette / Drasil

Generate all the things (focusing on research software)
https://jacquescarette.github.io/Drasil
BSD 2-Clause "Simplified" License
142 stars 26 forks source link

Use Label ShortNames in Traceability Matrix? #1539

Open smiths opened 5 years ago

smiths commented 5 years ago

Related to #1537, I wonder if we should use the short names for the generated traceability matrix. I like the long names for the expressiveness, but they make the formatting terrible in the LaTeX version. A short name wouldn't fix everything, but it would improve the situation. I searched through the previous issues and I saw a discussion of ShortName, which seems to be the right fit to me.

Rather than create a "to do" issue directly, I thought I'd first ask @JacquesCarette if this change makes sense. If it does, who would be best suited to carrying it out?

JacquesCarette commented 5 years ago

We should definitely do so - as long as we insure that, in both the tex and html, the generated short names in the matrix headers are also links to the definitions of those terms. And @Mornix is currently working on making the Traceability Matrix better, so he's quite well suited to take a look at this at the same time.

smiths commented 5 years ago

Sounds good!

Mornix commented 5 years ago

By “ShortName”s, i think there may be some overload here. The matrices already use ShortNames. Is a “ShortName” in this context something like IM1 or FR4?

smiths commented 5 years ago

@Mornix, I thought that each "chunk", like IM1, FR4, etc was given a long name and a short name? I searched through the past issues and found #689 (among others). I searched through the Drasil code and short names come up, but I don't know if it means that same thing that I thought it did. If we have Maybe ShortName maybe we didn't define it for most chunks of information? If that is the case, we should look at this again.

I found that I asked for short names back in #69. It looks like we decided to handle them with abbreviations. To be honest, I'm not sure how labels are currently handled. I thought we had an option for a short name, either generated, or user defined. If we don't have an option for a short name (maybe I should say short label?) for each chunk of knowledge, then I still think we should create this.

All I'm after is the standard LaTeX trick of having a long name defined, along with a short name. When space is limited the style sheet uses the short name.

JacquesCarette commented 5 years ago

Yes, we're abusing "short name". Mnemonic abbreviation is probably what we're looking for.

Mornix commented 5 years ago

This is possible by pulling different tables from ChunkDB with asOrderedList, however this may be inconsistent numerically at the moment due to outstanding issues: #1164 #1023. Once those have been completed, this should be able to be automated within docLang itself.

samm82 commented 5 years ago

Would this be able to be tackled now? @Mornix

Mornix commented 5 years ago

The two issues have been addressed so this is likely in the place where it can be tackled.

samm82 commented 5 years ago

To be clear @smiths, this issue is to use, for example, "FR5" as the shortname instead of "Calculate-Translation-Over-Time" throughout the whole document, not just in the traceability matrices? Just want to make sure I understand correctly before I start something.

Also, I'm not sure how this would be best accomplished. As mentioned, the short name should be chosen in docLang, since that's where we'll be sure to have all the chunks (so we know what number to give each one). However, when referencing a chunk, its shortname must be present, so that we can reference it.

I personally think each chunk would have a temporary shortname that is then set to the actual shortname in docLang, but I'm not sure if that would be good design/even work. Any feedback would be appreciated @Mornix!

Mornix commented 5 years ago

As far as I understand, the short, or numeric name, should only appear in the traceability matrix. That being said, if the traceability section exists, then where the chunk is initially placed (assumptions for example) should also include some mention of “A5” so the viewer is aware the relation. All other references to the chunks should retain their existing ShortName. A consistent ordering now exists for chunks present in ChunkDB. Anywhere asOrderedList is used returns a list following a consistent ordering and should be used to provide the numeric value for the numeric names.

Mornix commented 5 years ago

As an addendum, all of this should occur within DocLang. I don’t see a need for any other sub package code to be modified.

samm82 commented 5 years ago

Started in this commit: 0d4efdc0cded7afcc13e7efbb1b168f252182886. I left some comments on things I was stuck on.

smiths commented 5 years ago

To be clear @smiths, this issue is to use, for example, "FR5" as the shortname instead of "Calculate-Translation-Over-Time" throughout the whole document, not just in the traceability matrices? Just want to make sure I understand correctly before I start something.

@samm82, I think we should have the option of using the shortname throughout the document. This is a variability that our documentation recipe could set, so that individual users could decide how they want their documents to appear. The long names through off the formatting in many places. I could see someone wanting to use shortnames in those places.

samm82 commented 5 years ago

See discussion on this commit with @JacquesCarette and me.

samm82 commented 5 years ago

@JacquesCarette Can you look over my changes so far and see if you like the design? It involves the relevant chunk having a "marker" (which number it is) that is used to generate the shortname (ie. an InstanceModel with marker 2 will have shortname "IM2"). I've implemented it in the basic theory chunks, but not in the ConceptInstances yet. I just wanted to make sure I was on the right track before continuing.

JacquesCarette commented 5 years ago

I have indeed looked at the code you checked in for this, and it seemed fine.

samm82 commented 5 years ago

I've gotten the abbreviations working for the ConceptInstances, but the numbers are off. I'm almost 100% sure the problematic code is here, and I looked at the blame and @Mornix originally wrote it, so I'm wondering if you could help me figure it out.

https://github.com/JacquesCarette/Drasil/blob/5fed6703273da02f4a11862b57456fb0d7bd68d6/code/drasil-database/Database/Drasil/SystemInformation.hs#L128-L132

Currently, it assigns each ConceptInstance an increasing number, which currently leads to the following in Projectile: A1, A2, ... A13, A14, FR15, ... FR18, GS19, NFR20, ... NFR25. Looking at the code, it seems like it should (correctly) assign each "subgroup" of ConceptInstance with its own list, so that we'd have A1-14, FR1-4, GS1, and NFR1-6, but for some reason, that's not what it's doing.

There is also a similar function in ChunkDB.hs for (Concept c) => c: EDIT: This function is similar, but its arguments are anything that has an abbreviation, so this is not a possible source of problem (as far as I can tell). https://github.com/JacquesCarette/Drasil/blob/5fed6703273da02f4a11862b57456fb0d7bd68d6/code/drasil-database/Database/Drasil/ChunkDB.hs#L60-L62 https://github.com/JacquesCarette/Drasil/blob/5fed6703273da02f4a11862b57456fb0d7bd68d6/code/drasil-database/Database/Drasil/ChunkDB.hs#L49-L50

samm82 commented 5 years ago

I think I figured it out. It was related to the second related function - there should have been a similar function for ConceptInstances, but there wasn't. Moving the first function to be used in ChunkDB solved this issue.

samm82 commented 5 years ago

That's all done, so now I just have to figure out how to display these "shortnames" in the chunks/concept instances themselves (so the reader knows which one is which).