search

modelica / ModelicaStandardLibrary

Free (standard conforming) library to model mechanical (1D/3D), electrical (analog, digital, machines), magnetic, thermal, fluid, control systems and hierarchical state machines. Also numerical functions and functions for strings, files and streams are included.
https://doc.modelica.org
BSD 3-Clause "New" or "Revised" License
452 stars 165 forks source link

Fix ieee transactions style #4384

Closed gwr69 closed 2 months ago

gwr69 commented 2 months ago

The IEEE Transactions Style is unambiguously following American punctuation rules and commas are to be placed within quotation marks. I fixed this now in the documentation for Modelica.UsersGuide.Conventions.UsersGuide.References.

If you make a conscious choice to not follow IEEE Transactions Style then I would suggest you avoid confusion by referencing something like "Wikipedia Style" or "Modelica Style" instead?

HansOlsson commented 2 months ago

This PR seems like a complete mess when using the difference.

Regarding the actual idea I generally prefer the Logical Style or British Style https://en.wikipedia.org/wiki/Quotation_marks_in_English#British_practice - but I don't know how relevant due to the other issue.

There are also other differences in Wikipedia style - in particular it uses the same quotation mark on both sides (as currently in the text, right?), whereas IEEE transactions have different ones; i.e., straight not curly https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Quotation_characters

gwr69 commented 2 months ago

This PR seems like a complete mess when using the difference.

Regarding the actual idea I generally prefer the Logical Style or British Style https://en.wikipedia.org/wiki/Quotation_marks_in_English#British_practice - but I don't know how relevant due to the other issue.

There are also other differences in Wikipedia style - in particular it uses the same quotation mark on both sides (as currently in the text, right?), whereas IEEE transactions have different ones; i.e., straight not curly https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Quotation_characters

@HansOlsson

"The mess" could have been worse as chasing a single documentation info in Wolfram System Modeler causes >2000 file changes... I now used Visual Studio Code as to be minimally invasive. :)

Please look at Quotation mark as a more general reference.

One needs to distinguish "plain" and "typographic" quotation marks, e.g., straight vs. curly. That question to me is like the choice of font, e.g., with serifs and without. There is obviously both uses in either British and American English.

Note, that single quotation marks are still to my knowledge the primary quotation marks in British English. IEEE Transaction Style uses double quotation marks and places commas within the quotation.

HansOlsson commented 2 months ago

This PR seems like a complete mess when using the difference. Regarding the actual idea I generally prefer the Logical Style or British Style https://en.wikipedia.org/wiki/Quotation_marks_in_English#British_practice - but I don't know how relevant due to the other issue. There are also other differences in Wikipedia style - in particular it uses the same quotation mark on both sides (as currently in the text, right?), whereas IEEE transactions have different ones; i.e., straight not curly https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Quotation_characters

@HansOlsson

"The mess" could have been worse as chasing a single documentation info in Wolfram System Modeler causes >2000 file changes... I now used Visual Studio Code as to be minimally invasive. :)

Please look at Quotation mark as a more general reference.

One needs to distinguish "plain" and "typographic" quotation marks, e.g., straight vs. curly. That question to me is like the choice of font, e.g., with serifs and without. There is obviously both uses in either British and American English.

Yes, but the reason I considered it was that Wikipedia style differs in multiple ways from IEEE Transaction style (and similarly for other styles). In particular:

So, when considering if we should change from IEEE Transaction style to Wikipedia style we should consider all of them.

In this case HTML-document already use hard-coded straight quotes &quot;...&quot; not <q>...</q> - following Wikipedia. Using American Quoting style, combined with straight quotes doesn't really seem to conform to IEEE Transaction style.

Obviously we could use q-marks and then modify the CSS to have straight quotes - https://www.w3schools.com/Tags/tag_q.asp

Note, that single quotation marks are still to my knowledge the primary quotation marks in British English. IEEE Transaction Style uses double quotation marks and places commas within the quotation.

Good point. Note that Wikipedia style use double quotation marks.

gwr69 commented 2 months ago

Wikipedia is not an academic publishing style, is it? You are completely free in your choices, but if you reference some specification then you should follow it. :)

I now opened a pull request to master branch, which was the basis of my fork and likely explains the “mess.”

HansOlsson commented 2 months ago

Wikipedia is not an academic publishing style, is it? You are completely free in your choices, but if you reference some specification then you should follow it. :)

I totally agree that if we reference a specification we should follow it - that's why I investigated the curly vs. straight quotes.

Since MSL is a library, not an academic paper, I'm not too concerned whether it follows a specific academic publishing style.

I now opened a pull request to master branch, which was the basis of my fork and likely explains the “mess.”

We should probably continue the discussion there.