Apply style guide #2916

henrikt-ma · 2021-04-11T21:05:33Z

This is the follow-up to #2884, where the style guide was created. This PR is about getting the document more in line with that style guide.

Currently in Draft state to reflect that there are still rules in the style guide that I plan to apply as part of this PR. Note that making the document comply with the style guide in every aspect is beyond the scope of this PR (and not expected to be in the scope of any specific PR in the future either). For example, I have no intention of finding and fixing all occurrences of non-American English.

henrikt-ma · 2021-04-11T21:10:35Z

How about extending the style guide with a rule for always having a comma after the abbreviations i.e. and e.g.?

henrikt-ma · 2021-04-11T21:29:57Z

Opinions on top level vs top-level?

chapters/annotations.tex

chapters/classes.tex

HansOlsson · 2021-04-12T11:31:02Z

chapters/inheritance.tex

@@ -579,7 +580,7 @@ \section{Redeclaration}\label{redeclaration}
 A \lstinline!redeclare! construct as an element replaces the declaration of a local class or component with another declaration.
 Both \lstinline!redeclare! constructs work in the same way.
 The \lstinline!redeclare! construct as an element requires that the element is inherited, and cannot be combined with a modifier of the same element in the extends-clause.
-For modifiers the redeclare of classes uses a special short-class-definition construct; that is a subset of normal class definitions and semantically behave as the corresponding class-definition.
+For modifiers the redeclare of classes uses a special short class definition construct; that is a subset of normal class definitions and semantically behave as the corresponding class-definition.


Similarly. I believe we here should consistently view class-definition and short-class-definition as the grammar constructions; except I don't know what subset should be replaced with.

Fixed apart from the subset question. Please check this one extra carefully, as I also made some small improvements to language.

What about calling it a special case rather than a subset?

Special case sounds good.

Done. To avoid repeating the word special I removed it before short-class-definition. Please resolve if good.

chapters/inheritance.tex

Addressed comment (by Hans): - modelica#2916 (comment)

Addressing comment by Hans: - modelica#2916 (comment)

Based on comment by Hans: - modelica#2916 (comment)

By accident, this commit also includes added empty lines around sectioning commands, which should have been committed separately.

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Addressing comment by Hans: modelica#2916 (comment)

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

henrikt-ma · 2021-05-11T21:57:45Z

Looking good except for the many minor comments, in particular I don't like sentences starting with a non-capital letter even if part of inline-listing and prefer working around that.

I applied your suggestions, even though I think the other variant reads better. It would be great if we could get at least a third opinion on this, but we can open a separate style guide issue for this to get more input from the group. Going back to the other variant should be very easy in case that is the outcome of group discussion.

Edit: It's only the ones starting with The that I don't like. The ones starting with A read better now than before.

…e-guide

HansOlsson

Looking good now.

Closes modelica#2966

Correct double for introduced in #2916

Apply style guide hyphenation of "base-clock" and "sub-clock"

c840a02

henrikt-ma marked this pull request as draft April 11, 2021 21:05

henrikt-ma added 13 commits April 11, 2021 23:31

Write "base class" and "short class definition" with space

2c95ccc

Clean up punctuation in item list

630fad5

Use correct variants of "start"

908d6ac

Minor cleanup of white-space in listing

1181ad8

Write "nominal modifier" with space

c9ba57b

Use correct variants of "prefix"

23e452a

Write "conversion calls" with space

92788ac

Add "parameter-expression" to style guide

189fe8f

Add "array expression" and "record expression" to style guide

97e5819

Use correct variants of "expression"

7de39af

Use correct variants of "statement"

6d33c0b

Add more forms with "clause" and "loop" to style guide

a3d1a03

Fix build break

2e2899c

HansOlsson reviewed Apr 12, 2021

View reviewed changes

chapters/annotations.tex Outdated Show resolved Hide resolved

HansOlsson reviewed Apr 12, 2021

View reviewed changes

chapters/classes.tex Outdated Show resolved Hide resolved

HansOlsson reviewed Apr 12, 2021

View reviewed changes

chapters/inheritance.tex Outdated Show resolved Hide resolved

henrikt-ma added 9 commits April 12, 2021 17:32

Address comment regarding "extends-clause" and "short-class-definition"

c5e5310

Addressed comment (by Hans): - modelica#2916 (comment)

Change one case of "short class definition" -> "short-class-definition"

6ff2a37

Addressing comment by Hans: - modelica#2916 (comment)

Use language=grammar for modifiers in redeclaration and improve language

7c1dd27

Addressing comment by Hans: - modelica#2916 (comment)

One more "short class definition" -> "short-class-definition"

697baf1

Addressing comment by Hans: - modelica#2916 (comment)

Trade "a special" for "special case" later

30ee496

Based on comment by Hans: - modelica#2916 (comment)

Remove stray space in listing

c5caa1f

Use correct variants of "clause"

a21efbe

By accident, this commit also includes added empty lines around sectioning commands, which should have been committed separately.

Use correct variants of "loop"

0787fb9

Use correct variants of "branch"

6af5462

henrikt-ma and others added 20 commits May 11, 2021 23:33

Add suggested 'The' at start of sentence

5f4ab04

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

e6dfbac

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

6100103

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

944e2b7

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'A' at start of sentence

a0d5f6d

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Don't capitalize initial of list item, as suggested

80ed349

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Don't capitalize initial of list item, as suggested

ca20422

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

e3eb6b1

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

442d50c

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

9678041

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

77324f5

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

76b00e3

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

953231b

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'A' at start of sentence and go singular

a639fdd

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

1720656

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'A' at start of sentence and go singular

d5300ff

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Apply suggestion for nested when-statements

00c6042

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Add suggested 'The' at start of sentence

cb5a47f

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Change section title to 'Recommended selection of start-values'

02bad1b

Addressing comment by Hans: modelica#2916 (comment)

Add suggested 'The' at start of sentence

56f0be8

Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>

Merge remote-tracking branch 'central/master' into cleanup/apply-styl…

92ff1a7

…e-guide

henrikt-ma mentioned this pull request May 11, 2021

Don't start sentences with 'The' to avoid inline code lower case initial #2943

Closed

henrikt-ma requested a review from HansOlsson May 11, 2021 22:13

HansOlsson approved these changes May 12, 2021

View reviewed changes

HansOlsson merged commit 03f0c28 into modelica:master May 12, 2021

henrikt-ma deleted the cleanup/apply-style-guide branch May 12, 2021 09:53

HansOlsson added a commit to HansOlsson/ModelicaSpecification that referenced this pull request Aug 9, 2021

Correct double for introduced in modelica#2916

d493a8d

Closes modelica#2966

HansOlsson added a commit that referenced this pull request Aug 10, 2021

Merge pull request #2969 from HansOlsson/FixFor

747535c

Correct double for introduced in #2916

HansOlsson added the M36 For pull requests merged into Modelica 3.6 label Jul 6, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Apply style guide #2916

Apply style guide #2916

henrikt-ma commented Apr 11, 2021

henrikt-ma commented Apr 11, 2021

henrikt-ma commented Apr 11, 2021

HansOlsson Apr 12, 2021

henrikt-ma Apr 12, 2021

HansOlsson Apr 12, 2021

henrikt-ma Apr 13, 2021

henrikt-ma commented May 11, 2021 •

edited

Loading

HansOlsson left a comment

Apply style guide #2916

Apply style guide #2916

Conversation

henrikt-ma commented Apr 11, 2021

henrikt-ma commented Apr 11, 2021

henrikt-ma commented Apr 11, 2021

HansOlsson Apr 12, 2021

Choose a reason for hiding this comment

henrikt-ma Apr 12, 2021

Choose a reason for hiding this comment

HansOlsson Apr 12, 2021

Choose a reason for hiding this comment

henrikt-ma Apr 13, 2021

Choose a reason for hiding this comment

henrikt-ma commented May 11, 2021 • edited Loading

HansOlsson left a comment

Choose a reason for hiding this comment

henrikt-ma commented May 11, 2021 •

edited

Loading