Automatically collect abbreviations from generated `DocDesc`s by sarrasoussia · Pull Request #4363 · JacquesCarette/Drasil

sarrasoussia · 2025-09-07T14:20:29Z

Closes #4299
Based on #4323

Builds on #4695

code/stable/gamephysics/SRS/PDF/GamePhysics_SRS.tex

code/drasil-example/dblpend/lib/Drasil/DblPend/Body.hs

…ent section

…AbbS

code/drasil-docLang/lib/Drasil/Sections/TableOfAbbAndAcronyms.hs

code/drasil-docLang/lib/Drasil/ExtractDocDesc.hs

JacquesCarette · 2025-11-05T01:23:39Z

code/stable/gamephysics/SRS/Jupyter/GamePhysics_SRS.ipynb

    "|DD|Data Definition|\n",
    "|GD|General Definition|\n",
    "|GS|Goal Statement|\n",
+    "|GamePhysics|GamePhysics|\n",


I don't think GamePhysics should be treated as an abbreviation.

progName :: CI progName = commonIdeaWithDict "gamePhysics" (pn "GamePhysics") "GamePhysics" [physics]

GamePhysics (and the other examples you mentioned) all have code like this above because we require each of our case studies to have an abbreviation/codename.

So, should we loosen said restriction and remove the false abbreviation given to GamePhysics and co.? Or should we write a rule that filters out abbreviations in the table if they're equivalent to the terms. Or something else entirely?

Or should we write a rule that filters out abbreviations in the table if they're equivalent to the terms.

This might be a good rule to impose on our IdeaDicts, CIs, etc. in general.

An abbreviation is not a a 'codename'. If we require codenames, we should have a different data-structure for those.

We should not conflate different concepts.

Going back to this, while I agree with you, I think this is out of scope for this PR. We should fix it in another. I'm okay with this PR being blocked on that, but I'm also okay with pushing it to later in the name of merging in this PR (which is already quite large and a bit difficult to keep up to date with main).

Good: I think we should indeed fix that first.

I'm thinking a new ProgramName chunk, with fields name (or label) and some optional description. It should not implement the term lens. We're overloading CI too far here.

JacquesCarette · 2025-11-05T01:24:16Z

code/stable/gamephysics/SRS/Jupyter/GamePhysics_SRS.ipynb

    "<a id=\"Sec:LCs\"></a>\n",
    "\n",
-    "This section lists the likely changes to be made to the software.\n",
+    "This section lists the Likely Changes (LC) to be made to the software.\n",


likely changes should not be capitalized here (same with Unlikely Changes below)

Do we not always want to capitalize noun phrases when we introduce their acronyms?

I don't think so - but we should ask @smiths for another opinion.

I have always thought that capitalization should be used for introducing acronyms, but I recently learned that the rule is to capitalize the words in expanded form if the full phrase is a proper name or a formal title, like NASA. If the expanded phrase is not a proper noun, then the individual words are not capitalized, like research software engineer (RSE). According to ChatGPT, the APA, AMA, Chicago and IEEE all say this.

Do we have any way of knowing in our Drasil data whether the expanded form of our acronyms is a proper noun or not?

In theory, we have a way of knowing whether something is a proper noun or not. In practice, it has been abused, so it is not currently a proper source of 'truth'. But we could make it so.

Thanks for justifying that the individual words should not be capitalized.

Thank you @smiths!

Resolved in b76a720

Added PR #4695 as a dependency here too.

JacquesCarette · 2025-11-05T01:25:28Z

code/stable/glassbr/SRS/HTML/GlassBR_SRS.html

                  <td>Glass Type Factor</td>
                </tr>
+                <tr>
+                  <td>GlassBR</td>


Similarly, GlassBR should not be treated as an abbreviation.

code/stable/glassbr/SRS/Jupyter/GlassBR_SRS.ipynb

JacquesCarette · 2025-11-05T01:27:29Z

code/stable/pdcontroller/SRS/HTML/PDController_SRS.html

                  <td>proportional derivative</td>
                </tr>
+                <tr>
+                  <td>PD Controller</td>


Same "PD Controller" should not be an abbreviation

JacquesCarette · 2025-11-05T01:28:46Z

code/stable/projectile/SRS/HTML/Projectile_SRS.html

                  <td>Physical System Description</td>
                </tr>
+                <tr>
+                  <td>Projectile</td>


Projectile should not be an abbreviation

JacquesCarette · 2025-11-05T01:30:34Z

code/stable/swhs/SRS/Jupyter/SWHS_SRS.ipynb

    "|Refname|Reference Name|\n",
    "|SRS|Software Requirements Specification|\n",
    "|SWHS|Solar Water Heating System|\n",
+    "|SWHS|Solar Water Heating Systems Incorporating PCM|\n",


SWHS now has two meanings!

Agreed, but, similarly, I think this is out of scope for this PR. We will need to file an issue if this PR is approved+merged.

…AbbS

I'm not sure why this was removed to begin with. Bad merge?

code/drasil-docLang/lib/Drasil/DocumentLanguage.hs

…AbbS

code/stable/dblpend/SRS/mdBook/src/SecDocOrg.md

@smiths

nouns. Follows @smiths' comment on #4363: #4363 (comment)

@smiths

nouns. Follows @smiths' comment on #4363: #4363 (comment)

…tableAccAbbS

balacij · 2026-01-28T17:51:55Z

I think I'm going to call this PR "Ready for Review," @JacquesCarette @smiths. Regarding the paragraph previously added through this PR, as I mentioned in #4363 (comment), I've removed it. We should fix the root issue here in a subsequent PR. For now, I think this PR is fine enough.

There is the issue of the "code name"s being added to the table of abbreviations and acronyms, but I think we can file an issue to deal with this later.

smiths

I looked at the changes to stable. The changes look reasonable to me.

JacquesCarette · 2026-01-29T21:58:31Z

There's a conflict to resolve.

JacquesCarette · 2026-01-29T22:05:08Z

code/drasil-docLang/lib/Drasil/DocumentLanguage.hs

-mkSections si dd = map doit dd
+mkSections si dd =
+  let
+    splitByTAandA :: [[DocSection]]


I think this code should be refactored into even more generic kit. What you are doing is creating a 'view' (in this case, zooming in to RefSec), mapping onto one side of that view, and then putting everything back together.

A more refined way to do this would take a function (a -> Either b c) instead of a predicate, then two functions (b -> d) and (c -> d) for each side, then you could unEither. In the case below, it would actually be (a -> Either b a) and the function on the False stuff would be id.

JacquesCarette · 2026-01-29T22:07:27Z

code/drasil-docLang/lib/Drasil/ExtractDocDesc.hs

@@ -126,10 +126,10 @@ sentencePlate f = appendPlate (secConPlate (f . concatMap getCon') $ f . concatM
      (GDs s _ d _) -> def d ++ s ++ der d ++ notes d
      (IMs s _ d _) -> s ++ der d ++ notes d


Hmm, this part is still not addressed?

Sarra Soussia added 2 commits September 7, 2025 15:08

clean auto abbrv extraction code

952a528

stable

6de9dc5

sarrasoussia requested review from JacquesCarette, balacij, bmaclach, cd155, samm82 and smiths as code owners September 7, 2025 14:20

Sarra Soussia added 4 commits September 7, 2025 15:29

deleted abbreviationsList

04fd9af

fixed code errors

a3d111d

deleted acronyms def

d49a098

fixed unused imports errors

d45194d

balacij mentioned this pull request Sep 7, 2025

Auto-collect abbreviations for SRS Table of Abbreviations and Acronyms #4323

Closed

This comment was marked as outdated.

Sign in to view

balacij reviewed Sep 8, 2025

View reviewed changes

code/stable/gamephysics/SRS/PDF/GamePhysics_SRS.tex Outdated Show resolved Hide resolved

balacij reviewed Sep 8, 2025

View reviewed changes

code/drasil-example/dblpend/lib/Drasil/DblPend/Body.hs Outdated Show resolved Hide resolved

Sarra Soussia added 3 commits September 8, 2025 17:44

capitalize long abbreviation forms in the TAandA

30d057a

added missing abbrvs with an additional paragraph in the Org of Docum…

d07b293

…ent section

missing abrv displayed

41f6823

This comment was marked as outdated.

Sign in to view

removed all occurences of collectDocAbbrv from examples body.hs

4ae1045

This comment was marked as outdated.

Sign in to view

removed unecessary modules exposure

c072676

This comment was marked as outdated.

Sign in to view

Sarra Soussia added 5 commits September 9, 2025 13:40

line up fix

0d78660

restored deleted comments

f08e6e8

moved select to SearchTools file

0a8ece9

stable

dc1f995

mkSRS declaration fixed

621dd63

Merge branch 'main' of github.com:JacquesCarette/Drasil into tableAcc…

a6dccc7

…AbbS

This comment was marked as outdated.

Sign in to view

JacquesCarette requested changes Nov 5, 2025

View reviewed changes

balacij added 8 commits November 5, 2025 12:23

Remove ununecessary no-unused-top-binds pragma

4b811fa

Merge branch 'main' of github.com:JacquesCarette/Drasil into tableAcc…

17f6cd0

…AbbS

Add labelledContent back to SWHSNoPCM's ChunkDB.

b362518

I'm not sure why this was removed to begin with. Bad merge?

Add comments to new utils and avoid ++ in splitAtAll

78a9845

Remove duplicated comment

f5b45e7

Remove trailing whitespace again...

9c40fb2

Remove commented out code

248e342

Minimize diff to load duration factor

d022a3c

sarrasoussia mentioned this pull request Nov 11, 2025

Drasil Team Meeting - Tuesday, Nov 11, 1:45 pm, ITB/112 #4440

Closed

sarrasoussia force-pushed the tableAccAbbS branch from ab3e162 to e5e628f Compare December 9, 2025 19:36

balacij reviewed Dec 10, 2025

View reviewed changes

code/drasil-docLang/lib/Drasil/DocumentLanguage.hs Outdated Show resolved Hide resolved

balacij force-pushed the tableAccAbbS branch from 5c526b7 to d022a3c Compare January 28, 2026 14:31

balacij added 4 commits January 28, 2026 10:07

Merge branch 'main' of github.com:JacquesCarette/Drasil into tableAcc…

c6b93fb

…AbbS

Clean up leftover code in merge.

f0a0bb5

Add RefBy to rnHACK to get 'Referenced by' acronym in TabAccAbb

c832dc2

Hopefully fix build by removing duplicate export.

8f2b731

balacij reviewed Jan 28, 2026

View reviewed changes

code/stable/dblpend/SRS/mdBook/src/SecDocOrg.md Outdated Show resolved Hide resolved

Remove paragraph used to force in acronym gathering for TabAbbAcc

7d7aa62

balacij added a commit that referenced this pull request Jan 28, 2026

Only titleize nouns on abbreviation/acronym introduction for proper

f42dcf9

nouns. Follows @smiths' comment on #4363: #4363 (comment)

Only titleize nouns on abbreviation/acronym introduction for proper

ea0ecb4

nouns. Follows @smiths' comment on #4363: #4363 (comment)

balacij mentioned this pull request Jan 28, 2026

introduceAbb: Only titleize nouns on abbreviation/acronym introduction for proper nouns. #4695

Merged

balacij added 2 commits January 28, 2026 12:29

Merge branch 'introduceAbb' of github.com:JacquesCarette/Drasil into …

e21e16f

…tableAccAbbS

Fix introduceAbbPlrl + stabilize

b76a720

smiths approved these changes Jan 28, 2026

View reviewed changes

JacquesCarette requested changes Jan 29, 2026

View reviewed changes

		@@ -126,10 +126,10 @@ sentencePlate f = appendPlate (secConPlate (f . concatMap getCon') $ f . concatM
		(GDs s _ d _) -> def d ++ s ++ der d ++ notes d
		(IMs s _ d _) -> s ++ der d ++ notes d

Conversation

sarrasoussia commented Sep 7, 2025 • edited by balacij Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

balacij Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

balacij commented Jan 28, 2026

Uh oh!

smiths left a comment

Choose a reason for hiding this comment

Uh oh!

JacquesCarette commented Jan 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sarrasoussia commented Sep 7, 2025 •

edited by balacij

Loading

balacij Jan 28, 2026 •

edited

Loading