-
Notifications
You must be signed in to change notification settings - Fork 26
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Use Label ShortNames in Traceability Matrix? #1539
Comments
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. |
Sounds good! |
By “ShortName”s, i think there may be some overload here. The matrices already use |
@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 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. |
Yes, we're abusing "short name". Mnemonic abbreviation is probably what we're looking for. |
Would this be able to be tackled now? @Mornix |
The two issues have been addressed so this is likely in the place where it can be tackled. |
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 I personally think each chunk would have a temporary shortname that is then set to the actual shortname in |
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 |
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. |
Started in this commit: 0d4efdc. I left some comments on things I was stuck on. |
@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. |
See discussion on this commit with @JacquesCarette and me. |
@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 |
I have indeed looked at the code you checked in for this, and it seemed fine. |
I've gotten the abbreviations working for the Drasil/code/drasil-database/Database/Drasil/SystemInformation.hs Lines 128 to 132 in 5fed670
Currently, it assigns each There is also a similar function in Drasil/code/drasil-database/Database/Drasil/ChunkDB.hs Lines 60 to 62 in 5fed670
Drasil/code/drasil-database/Database/Drasil/ChunkDB.hs Lines 49 to 50 in 5fed670
|
I think I figured it out. It was related to the second related function - there should have been a similar function for |
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). |
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?
The text was updated successfully, but these errors were encountered: