Changes

Initial commit of documents for MCP-0033

Minor corrections, mostly language and formatting

Update the predefined plots to add HTML-caption, sub-plot title and optional identifier.
Closes #2363

Update predefined-plots.md

Batter -> Battery (twice)

Updates after demonstration of prototype

Clean up and updating proposal with features demonstrated at 100th design meeting

These changes are mainly about renaming and reorganizing features presented or planned at the previous design meeting.

References and comparisons to the current use of predefined plots in Wolfram SystemModeler have been removed.

The handling of axis boundaries have been defined by making the choice of unit explicit.

Fix broken markdown from previous commit

Drop the top level Figures container in favor of reusing Documentation

Having figures as part of the Documentation has become very natural now that they also include captions, and that part of the current content of the 'info' might end up being migrated to figure captions instead.

Second, the figures are expected to be heavily linked from the 'info', which is another reason for keeping them close together.

Third, this avoids the use of a container record with just a single record member.

Text markup for captions

Added example figure from the prototype

Update predefined-plots.md

Consistently using record constructors.

Clean up whitespace in example of Figure

Clarifications regarding Figure 'group'

Specifying behavior of undefined and empty Curve 'legend'

State uniqueness requirement for Figure and Plot 'identifier'

Clarify rules for Figure and Plot 'title', and relation to plot labels

Move preferredView and DocumentationClass to the more logical place "Annotations for the Graphical User Interface"

Initial conversion of the markdown content to latex and integration of the text

Describe all the attributes of Figure in the text

Explicitly point out all attributes where variable replacements might be used

Removing redundant statement regarding vendor annotations (they can appear anywhere in any annotation)

Be even more specific about where variable replacements can be used

Fix typo

Fix whitespace

Use the nonnormative macro

Restore list that was lost in translation from markdown

Remove outdated restriction to simulation models in ReadMe.md

Fix typo

Relax the uniqueness requirements of plot identifiers

Clarify the uniqueness of Figure and Plot identifiers

Move \doublelabel out of \subsection argument

Add link to collection of examples in ReadMe.md

Incorporate suggestions from #2578

Clarify that behavior is unspecified for:
 - Curves where x or y does not designate a variable
 - Unknown units or incompatible with the plotted variable

Clarify that leading and ending newlines are ignored in captions (#2581)

Make Figure title optional as decided at the 101th design meeting (#2580)

Fix typos and improved wording reported by @matlelenz

text graphical -> text graphical primitive

Use \lstinline on 'Plot' and 'title'

Co-authored-by: Otto Tronarp <otto@tronarp.se>

Elaborate on the inheritance of figures

Explain 'preferred' plot in a more open way

Addressing comment by @maltelenz.

Add missing 'as'

As suggested by @otronarp.

Co-authored-by: Otto Tronarp <otto@tronarp.se>

Remove empty line at beginning of file

Use pseudocode record for 'Documentation' annotation

Addressing review comment by @HansOlsson.

Use \lstinline for 'ExternalObject'

Use \lstinline for 'noEvent'

Clarify that it's an error if cref does not designate a scalar variable

Clarify the behavior for unknown and incompatible units

Fix broken merge

Co-authored-by: Henrik Tidefelt <henrikt@wolfram.com>

Move things related to Axis.label into the same paragraph

Clarify that Axis.unit is required when specifying axis bounds

Make Axis.unit default to "" (without yet specifying what the default means)

First try at defining the meaning of empty Axis.unit

Mandate that Axis.unit is used for axis tick labels

Separate meanings of presence of axis bounds and presence of Axis.unit

Ignore 'min' and 'max' when 'unit' is not recognized

Say "\lstinline!start! attribute"

Remove extra period at end of sentence

Move MCP state to 'Under Evaluation'

Use \lstinline on 'homotopy'

With change of styling, 'the ... operator' got redundant and was removed in all places but one.

Clean up whitespace in listing related to pure functions

Add missing \lstinline for 'homotopy'

Text styling cleanup related to 'annotation'

Text styling cleanup related to 'assert'

Text styling cleanup related to 'block'

Styling related to 'break' (including 'Connections')

Cleanup related to 'connector'

Cleanup related to 'constant'

Cleanup related to 'discrete'

Cleanup related to 'each'

Cleanup related to 'elsewhen'

Add comment regarding 'exit' as keyword

Cleanup related to 'extends'

Cleanup related to 'external'

Cleanup related to 'final'

Cleanup related to 'flow'

Cleanup related to 'function'

Cleanup related to 'input'

Cleanup related to 'import'

Cleanup related to 'loop'

Add comment regarding keyword status of 'nondiscrete'

Cleanup related to 'parameter'

Cleanup related to 'partial'

Cleanup related to 'redeclare'

Cleanup related to 'return'

Cleanup related to 'terminate'

Add comment regarding the only occurrence of 'while-loop'

Cleanup related to 'pure' and 'impure'

Cleanup related to 'transition' and 'connect'

Cleanup related to 'semiLinear'

Cleanup related to 'inStream' and 'actualStream'

Cleanup related to 'spatialDistribution'

Cleanup related to 'getInstanceName'

Cleanup related to 'noEvent' and 'smooth'

Cleanup related to 'sample'

Cleanup related to 'pre'

Cleanup related to 'reinit'

Cleanup related to 'previous'

Cleanup related to recognized named in synchronous

Cleanup related to 'String'

Cleanup related to 'Boolean'

Cleanup related to 'Integer'

Cleanup related to 'Real'

Restructure CSS files to make tracking actual changes easier

Improve HTML layout

Change .ltx_page_main max-width to 80em

The em unit seems like a more appropriate for the width of a text.

Cleanup related to 'textColor'

Cleanup related to 'arrowSize', 'lineThickness', 'borderPattern', 'Arrow'

Cleanup of more lower camel case identifiers

Cleanup related to upper camel case identifiers

Clean up whitespace

This includes getting rid of some tabs and making sure that lines of some listings fit inside the text width.

One more case of 'Boolean'

Let the navbar inherit its text color

Use inherited color for links

A similar change is proposed for the PDF build in #2690.

Invert colors for sidebar and page header

When looking around on the internet, using an inverted color scheme for side bars seems pretty common, and I think it is for good reasons.

Update table to follow new style

Follow surrounding style of empty line in the source after a sectioning command

Introduce new dialect [nocomment]modelica for making comments appear as normal code

Improving specification of escape sequences

Add styling of 'x' and 'y' denoting axes

Using match would have been an alternative, but \lstinline was chosen for symmetry with the styling of 'curves'.

Reference table in text

Fix typo reported by @maltelenz

Co-authored-by: Malte Lenz <malte.lenz@gmail.com>

Use 'example.org' instead of 'bad.org' in crazy example

Fix three cases of 'parameter-expression' -> 'parameter expression'

Make assertion level a parameter expression

Change 'a discrete-time variables' -> 'a discrete-time variable'

Fixes #2699

State solvability requirements for discrete-valued variables

According to phone meeting decision on #2639.

Remove meaningless braces around 'unique'

Use \cref to reference item of enumeration

Put spaces in correct locations of overloaded constructor call

Fix some white-space irregularities in the grammar

Fix more white-space irregularities

Partly fix white-space irregularities in lexer rules

Fix two more minor white-space irregularities

Update comment about LaTeXML issue being fixed on their 'master'

Fix typos in spec (#2695)

* Fix typo in operatorsandexpressions.tex
* Fixing little typos in spec

Deprecate byte order mark (#2696)

* Deprecate use of UTF-8 byte order mark
* Change 'whitespace' -> 'white-space' everywhere

Cleanup listings related to external-clauses (#2688)

* Improve readability of external-clauses
* Clean up whitespace in listings related to external functions
* Remove bad escaping in 'size\_t' inside lstlisting
* Suggest that we add syntax highlighting for 'size_t' in C
This would be similar to how we do syntax highlighting of certain recognized identifiers in Modelica, apart from the keywords.
* Indent 'external' with to same level as 'function'
The annotation of the external clause is indented one level deeper than the external-function-call, to avoid mixing it up with the function annotation.

Clarify that equations in discrete-time Real variables are only solved at events

 Use non-inverted styling of sidebar, with dividers in logo colors

Remove unused and (basically) unmodified copy of LaTeXML CSS file

The only difference to the original file I can see is formatting of the CSS file itself.

Rename 'LaTeXML-navbar-left.css' -> 'MLS-navbar-left.css'

This reflects more clearly that our CSS is now quite different from the LaTeXML file it was developed from.

Add comment regarding LaTeXML failure to treat \lstinline properly inside \caption

Fix lost white-space after \textregistered (#2708)

* Fix lost white-space after \textregistered
* Add braces around argument to \textsuperscript

Tone down syntax highlighting of recognized identifiers (#2690)

* Change syntax color from red to brown
* Adjust syntax highlighting colors
* Make plain 'keyword' style pop out in bright red (should never be seen)
* Add commented-out attempt at getting nice listings comments in PDF build
* Use the hyperref 'hidelinks' option to avoid distracting links
Readers will expect things a linked anyway.
* Use darker green for comments
* Remove special de-highlighting of semicolon
Regardless of whether this is nice or not for the semicolon at the end of elements, it makes no sense to apply styling that also affects the semicolon used as an array concatenation operator.

Ignore errors in Makefile targets 'clean-pdf' and 'clean-html'

Revert to off-the-shelf LaTeXML-maybeMathjax.js

Our file was identical to the original one, so it is better to just as for the original, so that we can automatically benefit from upstream improvements.

Note that our copy was called 'LaTeXML-maybeMathJax.js' (upper case 'J' in 'Jax'), while the original file is called 'LaTeXML-maybeMathjax.js'.

Update

Fix incorrect use of underscore in grammar rule names

Break too long line before 'textString'

Break too long line before 'OnMouseUpSetBoolean'

Also moving paragraph break to get correct association of preceding paragraph.

Remove misplaced semicolon after 'interaction' annotation

Add missing '\lstinline' before '!Real!'

Cleanup related to 'OldModifier'

Say 'The meanings of these annotations are'

Use line breaks to reflect grouping inside 'Access' annotation

Let's have a look at sentence-based line breaks

In response to review comment:
- https://github.com/modelica/ModelicaSpecification/pull/2627#discussion_r519734647

Update pure function optimization example, avoiding long lines

Rephrase introduction to vectorization rules

The previous formulation had a passive form that didn't really work as an introduction to the list of rules.

Clear up description of element-wise evaluation of vectorized call

Fix missing \lstinline of 'Library' (annotation)

Remove empty line in assert example string literal

Add missing \lstinline on 'in0', 'in1', 'out0', 'out1'

Break long line with 'spatialDistribution'

Improve sub-clock named argument styling and sentence

Don't split sentence over listing

Add missing \lstinline for 'Boolean'

Suggest \linebreak[4] before \lstinline to avoid comma after line break

Use pseudo-code <and then> to shorten long lines

Improve formatting of spatialDistribution pseudo-code

Break long line in 'cardinality' example

Fix \lstinline formatting of multi-line comment syntax

Refactor preamble to allow parts be shared with figures

Move come content out of preamble.tex to make it more package-like

Rename math command \pdfrac -> \udfrac (and introduce \pdfrac for comparison)

Update figures after change of syntax highlighting

Text from decision. (#2711)

* Text from decision.
Closes #2693

Force a line break after paragraph to not conflict the display

The following frame box gets distorted if the code section does not start at the beginning of a line.

One could argue that paragraph headings should always have a line break after the name. 

Collapse navbar unless window is really wide (#2716)

* Minor white-space cleanup
* Collapse navbar (expand on hover) unless window is really wide

Point to correct CSS file in Jenkinsfile

By the way, @sjoelund, can we get rid of old files that are no longer in use?

Allow LaTeXML to process raw .sty files

Fixes #2720

Make navbar collapse to top left corner

This results in a menu that is easier to expand using a finger on a small touch screen, and at the same time giving more horizontal space for reading the main content.

Don't show links to previous and next chapter

Reasons to not show:
- Highly unlikely to be used (more meaningful when each page is short, and a reader is expected to read one page after another).
- Occupies space that is precious on small screens.
- Current layout breaks when window is so narrow that these links would overlap.

Style "Contents" on front page like a chapter title

Remove \includegraphics 'width' specifications in commented-out code

Use \vspace instead of \vspace* in 'synopsis' environment

I don't see any reason why the starred form was introduced in the first place, so it's probably better to go with the more intelligent form.

Use 'titlepage' environment instead of \maketitle, and shorten \title

This makes the \title work better in the LaTeXML output.

Extract \tableofcontents from abstract.tex

Sentence-based line breaking in abstract.tex

Use \mlsversion in abstract

Use \firstuse and period in footnote for "Modelica"

Work around LaTeXML issue with the 'abstract' environment

This also restores the 3.4 look with the abstract on the PDF front page.

Don't show date after chapter title introduced in LaTeXML 0.8.5

Write 'version' with lower case when no longer at beginning of line

This adds separation of "Modelica Language Specification" from its version.

Update to latexml 0.8.5

Fix typo in comment

Set language=grammar for \lstinline grammar rule

Add reference to where "builtin" external language is used