Updating Outputs of Data Definitions

[niazim3]

By redefining a term like "loadDF" from .GlassBr from (nounPhraseSP "Load Duration Factor") to (nounPhraseSP "load duration factor"), there is no longer a need to use the sLower function when calling the term.
However, renaming these terms is now causing inconsistencies between the required and generated output whenever they are called as QDefinition types instead of Sentence types (e.g. line 563 within the definition of s7_1_list).

[szymczdm]

This is just a simple mix-up of using phrase instead of titleize on line 561.

[niazim3]

It actually turns out that the inconsistency is being caused from within dataDefns (line 386 of GlassBr\Example.hs)...

[niazim3]

Within the Data Definition table, terms are mostly capitalized.
In order to remove the sLower function, I was thinking of changing how every term is defined to have only lowercase letters (for example:
from (loadDF = fromEqn' (lDurFac ^. id) (nounPhraseSP "LoadDuration Factor") (Atomic "LDF") loadDF_eq )
to (loadDF = fromEqn' (lDurFac ^. id) (nounPhraseSP "load duration factor") (Atomic "LDF") loadDF_eq ) from file GlassBr\Example.hs).
However, I am not sure if it is the correct solution if the capitalization is a writing convention for documentation.
So, does the capitalization of terms matter in scientific documentation? @smiths

[szymczdm]

I was thinking of changing how every term is defined to have only lowercase letters

As long as they are not proper nouns, this would be the correct approach. The data definitions being lowercase makes sense as they need to be overhauled, but that will require a bit of design.

[smiths]

As far as I am aware, there is nothing in scientific documentation that requires terms to use upper case letters. However, there are times when capitals are used so that the term stand out in a sentence. Also, using uppercase helps logically link multi-word terminology. For instance, load duration factor does not stand out in this sentence; it also isn't clear that it is logically one concept: Load Duration Factor. The same thing happens with terms like module guide. If these terms appear in the text, I would like them to be capitalized. Capitals are also necessary when an acronym is defined. The usual convention is to capitalize the letters that are used by the acronym, like Load Duration Factor (LDF). Writing load duration factor (LDF) does not convey the necessary information as efficiently.

If the question is whether the terms should be in lower case and then capitalized when needed, or the term should be upper case and made lower case when needed, I don't know the answer. We should make the default the more common case. Given that Dan has a comment about suggesting that the terms should be lower case, I'm guessing that is the more common case? I'm okay with that, as long as we can get an upper case version when we need it.

[szymczdm]

We may need to wait until I've finished #104 to fix the data definition descriptions.

[niazim3]

@szymczdm
I believe this issue can be closed? The description modification in DataDefs is related to issue #104. The current Data Definitions' description are as follows:

@smiths Is the above acceptable output for the data definitions? The additional information that is missing still needs to be generated, however, this issue is being tracked in #350.

[njericha]

duplicate of #350

[smiths]

@niazim3 , I like the data definition (with the missing information from #350 added back in), but if I am being picky, I would like to see two things: 1) the units field filled in with something, even if it is dimensionless, or not applicable. I also would prefer each letter of an expanded acronym to be capitalized, so that it would read LDF is the Load Duration Factor.

[niazim3]

Thank you for the feecback @smiths.
Since the following need to be updated for the DataDefinitions, and are still related to this issue, I think it should be reopened.

• "fill units field with something, even if it is dimensionless, or not applicable"
• each letter of an expanded acronym should be capitalized

[njericha]

@smiths should all term names be capitalized in the description? (should we capitalize "load duration factor", "duration of load", and "surface flaw parameter")

[niazim3]

A possible rule to follow when deciding whether a term should be capitalized or not:
capitalize chunks whose symbols are the same concept's acronym.

In order to do this:
--> need to get the chunks to build off of the CIs of the same concept so some type of relationship between 2 chunk types is present?
or
--> create a new chunk type that holds both a symbol and abbreviation that is used to build DataDefns?
or
--> check if the term is present in both the Table of Symbols and Table of Acronyms in the document to determine whether or not the chunk should be capitalized?

Would this be going in the correct direction?

[smiths]

In answer to the question from @njericha , I am talking about acronyms only. For an acronym each letter of its expansion should be capitalized. This is standard style with acronyms. This can be seen in style guides, such as the one at:

https://www.e-education.psu.edu/styleforstudents/c2_p9.html

"Always write out the first in-text reference to an acronym, followed by the acronym itself written in capital letters and enclosed by parentheses. Subsequent references to the acronym can be made just by the capital letters alone. For example:

Geographic Information Systems (GIS) is a rapidly expanding field. GIS technology . . ."

Technically for an acronym the letters that are pulled out for the acronym are capitalized in the expansion. This seems to fiddly for the moment, so I think we are good with just capitalizing the first letter in each word of the expansion of the acronym, like LDF.

("duration of load" and "surface flaw parameter" are not acronyms, so they shouldn't be capitalized.)

[smiths]

We agree that we do not need to worry about this issue.