Modelica.UsersGuide.Conventions.Documentation.Format

In this section the format UsersGuide of the HTML documentation are specified. The structure of the documentation is specified separately.

Paragraphs

1. In each section the paragraphs should start with <p> and terminate with </p>.
2. Do not write plain text without putting it in a paragraph.
3. No artificial line breaks <br> should be added within text paragraphs if possible. Use separate paragraphs instead.
4. After a colon (:) continue with capital letter if new sentence starts; for text fragments continue with lower case letter

Emphasis

1. For setting text in strong font (normally interpreted as boldface) the tags <strong> and </strong> have to be used.
2. For emphasizing text fragments <em> and </em> has to be used.
3. Modelica terms such as expandable bus, array, etc. should not be emphasized anyhow.

Capitalization of Text

1. Table headers and entries should start with capital letters
2. Table entries should start with lower case letter if only text fragments are used.
3. Table and figure captions start with a capital letter

Extends from Modelica.Icons.Information (Icon for general information packages).

Package Content

Name	Description
Cases	Cases
Code	Code
Equations	Equations
Figures	Figures
Hyperlinks	Hyperlinks
Lists	Lists
References	References
Tables	Tables

Modelica.UsersGuide.Conventions.Documentation.Format.Cases

In the Modelica documentation sometimes different cases have to be distinguished. If the case distinction refers to Modelica parameters or variables (Boolean expressions) the comparisons should be written in the style of Modelica code within <code> and </code>

Examples

Example 1

<p>If <code>useCage == true</code>, a damper cage is considered in the model...</p>

appears as

If useCage == true, a damper cage is considered in the model...

For more complex case scenarios, an unordered list should be used. In this case only Modelica specific code segments and Boolean expressions.

Example 2

<ul>
  <li> If <code>useCage == true</code>, a damper cage is considered in the model.
       Cage parameters must be specified in this case.</li>
  <li> If <code>useCage == false</code>, the damper cage is omitted.</li>
</ul>

appears as

• If useCage == true, a damper cage is considered in the model. Cage parameters must be specified in this case.
• If useCage == false, the damper cage is omitted.

In a more equation oriented case, additional equations or code segments can be added.

Example 3

<ul>
  <li>if <code>usePolar == true</code>, assign magnitude and angle to output <br>
  <!-- insert graphical representation of equations -->
  y[i,1] = sqrt( a[i]^2 + b[i]^2 ) <br>
  y[i,2] = atan2( b[i], a[i] )
  </li>
  <li>if <code>usePolar == false</code>, assign cosine and sine to output <br>
  <!-- insert graphical representation of equations -->
  y[i,1] = a[i] <br>
  y[i,2] = b[i]
  </li>
</ul>

appears as

• if usePolar == true, assign magnitude and angle to output
  
  
• if usePolar == false, assign cosine and sine to output
  
  

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Conventions.Documentation.Format.Code

Modelica code conventions of class and instance names, parameters and variables are specified separately. In this section it is summarized how to refer to Modelica code in the HTML documentation.

1. For constants, parameters and variables in code segments <code> and </code> should to be used, e.g.,
   parameter Modelica.Units.SI.Time tStart "Start time"
2. Write multi or single line code segments as quoted preformatted text, i.e., embedded within <blockquote><pre> and </pre></blockquote> tags.
3. Multi line or single line code shall not be additionally indented.
4. Inline code segments may be typeset with <code> and </code>.
5. In code segments use bold to emphasize Modelica keywords.

Examples

Example 1

<blockquote><pre>
<strong>connector</strong> Frame
   ...
   <strong>flow</strong> SI.Force f[3] <strong>annotation</strong>(unassignedMessage="...");
<strong>end</strong> Frame;
</pre></blockquote>

appears as

connector Frame
   ...
   flow SI.Force f[3] annotation(unassignedMessage="...");
end Frame;

Example 2

<blockquote><pre>
<strong>parameter</strong> Modelica.Units.SI.Conductance G=1 "Conductance";
</pre></blockquote>

appears as

parameter Modelica.Units.SI.Conductance G=1 "Conductance";

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Conventions.Documentation.Format.Equations

In the context of HTML documentation equations should have a graphical representation in PNG format. For that purpose tool specific math typing capabilities can be used. Alternatively the LaTeX to HTML translator LaTeX2HTML, or the Online Equation Editor or codecogs can be used.

A typical equation, e.g., of a Fourier synthesis, could look like

or

In an alt tag the original equation should be stored, e.g.,

<img
 src="modelica://Modelica/Resources/Images/UsersGuide/Conventions/Documentation/Format/Equations/sample.png"
 alt="y=a_1+a_2">

If one wants to refer to particular variables and parameters in the documentation text, either a graphical representation (PNG file) or italic fonts for regular physical symbols and lower case Greek letters should be used. Full word variables and full word indices should be spelled within <code> and </code>. Vector and array indices should be typeset as subscripts using the <sub> and </sub> tags.

Examples for such variables and parameters are: φ, φ_ref, v₂, useDamperCage.

Numbered equations

For numbering equations a one row table with two columns should be used. The equation number should be placed in the right column:

<table border="0" cellspacing="10" cellpadding="2">
  <tr>
    <td><img
    src="modelica://Modelica/Resources/Images/UsersGuide/Conventions/Documentation/Format/Equations/sample.png"
    alt="y=a_1+a_2"> </td>
    <td>(1)</td>
  </tr>
</table>

appears as:

(1)

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Conventions.Documentation.Format.Figures

Figures should in particular be included to examples to discuss the problems and results of the respective model. The library developers are yet encouraged to add figures to the documentation of other components to support the understanding of the users of the library.

1. Figures have to be placed outside of paragraphs to be HTML compliant.
2. Figures need to have at least a src and an alt attribute defined to be HTML compliant.
3. Technical figures should be placed within a table environment. Each technical figure should then also have a caption. The figure caption starts with a capital letter.
4. Illustration can be embedded without table environment.

Location of files

The PNG files should be placed in a folder which exactly represents the package structure.

Examples

Example 1

This example shows how an illustration should be embedded in the Example PID_Controller of the Blocks package.

<img src="modelica://Modelica/Resources/Images/Blocks/PID_controller.png"
     alt="PID_controller.png">

Example 2

This is a simple example of a technical figure with caption.

<table border="0" cellspacing="0" cellpadding="2">
  <caption align="bottom">Caption starts with a capital letter</caption>
  <tr>
    <td>
      <img src="modelica://Modelica/Resources/Images/Blocks/PID_controller.png"
           alt="PID_controller.png">
    </td>
  </tr>
</table>

Example 3

To refer to a certain figure, a figure number may be added. In such case the figure name (Fig.) including the figure enumeration (1,2,...) have to be displayed bold using <strong> and </strong>.

The figure name and enumeration should look like this: Fig. 1:

Figures have to be enumerated manually.

<table border="0" cellspacing="0" cellpadding="2">
  <caption align="bottom"><strong>Fig. 2:</strong> Caption starts with a capital letter</caption>
  <tr>
    <td>
      <img src="modelica://Modelica/Resources/Images/Blocks/PID_controller.png"
           alt="PID_controller.png">
    </td>
  </tr>
</table>

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Conventions.Documentation.Format.Hyperlinks

1. Hyperlinks should always be made when referring to a component or package.
2. The hyperlink text in between <a href="..."> and </a> should include the full main package name.
3. A link to an external component should include the full name of the package that it is referred to.
4. Modelica hyperlinks have to use the scheme "modelica://..."
5. For hyperlinks referring to a Modelica component, see Example 1 and 2.
6. No links to commercial web sites are allowed.

Examples

Example 1

<a href="modelica://Modelica.Mechanics.MultiBody.UsersGuide.Tutorial.LoopStructures.PlanarLoops">
         Modelica.Mechanics.MultiBody.UsersGuide.Tutorial.LoopStructures.PlanarLoops</a>

appears as

Example 2

<p>
  The feeder cables are connected to an
  <a href="modelica://Modelica.Electrical.Machines.BasicMachines.InductionMachines.IM_SquirrelCage">
  induction machine</a>.
</p>

appears as

The feeder cables are connected to an induction machine.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Conventions.Documentation.Format.Lists

1. Lists have to be placed outside of paragraphs to be HTML compliant.
2. Items of a list shall start with
   1. a capital letter if each item is a full sentence
   2. a small letter, if only text fragments are used or the list is fragment of a sentence

Examples

Example 1

This is a simple example of an enumerated (ordered) list

<ol>
  <li>item 1</li>
  <li>item 2</li>
</ol>

appears as

1. item 1
2. item 2

Example 2

This is a simple example of an unnumbered list.

<ul>
  <li>item 1</li>
  <li>item 2</li>
</ul>

appears as

• item 1
• item 2

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Conventions.Documentation.Format.References

1. Refer to references by [1], [Andronov1973], etc. by hyperlink and summarize literature in the references subsection of Conventions.UsersGuide.References.
2. There has to be made at least one citation to each reference.

Examples

Example 1

<p>
More details about electric machine modeling
can be found in [<a href="modelica://Modelica.UsersGuide.Conventions.UsersGuide.References">Gao2008</a>]
and
[<a href="modelica://Modelica.UsersGuide.Conventions.UsersGuide.References">Kral2018</a>, p. 149].
</p>

appears as

More details about electric machine modeling can be found in [Gao2008] and [Kral2018, p. 149].

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Conventions.Documentation.Format.Tables

1. Tables should always be typeset with <table> and </table>, not with <pre> and </pre>.
2. Tables have to be placed outside of paragraphs to be HTML compliant.
3. Each table must have a table caption.
4. Table headers and entries start with capital letters.

Examples

Example 1

This is a simple example of a table.

<table border="1" cellspacing="0" cellpadding="2">
  <caption align="bottom">Caption starts with a capital letter</caption>
  <tr>
    <th>Head 1</th>
    <th>Head 2</th>
  </tr>
  <tr>
    <td>Entry 1</td>
    <td>Entry 2</td>
  </tr>
  <tr>
    <td>Entry 3</td>
    <td>Entry 4</td>
  </tr>
</table>

appears as

Example 2

In this case of table captions, the table name (Tab.) including the table enumeration (1,2,...) has to be displayed bold using <strong> and </strong>. The table name and enumeration should look like this: Tab. 1: Tables have to be enumerated manually.

<table border="1" cellspacing="0" cellpadding="2">
  <caption align="bottom"><strong>Tab 2:</strong> Caption starts with a capital letter</caption>
  <tr>
    <th>Head 1</th>
    <th>Head 2</th>
  </tr>
  <tr>
    <td>Entry 1</td>
    <td>Entry 2</td>
  </tr>
  <tr>
    <td>Entry 3</td>
    <td>Entry 4</td>
  </tr>
</table>

appears as

Extends from Modelica.Icons.Information (Icon for general information packages).