Package Modelica.​UsersGuide.​Conventions.​Documentation.​Format
Format

Information

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 Contents

NameDescription
CasesCases
CodeCode
EquationsEquations
FiguresFigures
HyperlinksHyperlinks
ListsLists
ReferencesReferences
TablesTables

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​Cases
Cases

Information

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>

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 a 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

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

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

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​Code
Code

Information

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.SIunits.Time tStart "Start time"
  2. Write multi or single line code segments using <pre> and </pre>.
  3. Multi line or single line code shall not be indented.
  4. Inline code segments may be typeset with <code> and </code>.
  5. In code segments use bold to emphasize Modelica keywords.
Example 1
<pre>
<strong>connector</strong> Frame
   ...
   <strong>flow</strong> SI.Force f[3] <strong>annotation</strong>(unassignedMessage="...");
<strong>end</strong> Frame;
</pre>

appears as

connector Frame
   ...
   flow SI.Force f[3] annotation(unassignedMessage="...");
end Frame;
Example 2
<pre>
<strong>parameter</strong> Modelica.SIunits.Conductance G=1 "Conductance";
</pre>

appears as

parameter Modelica.SIunits.Conductance G=1 "Conductance";

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

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​Equations
Equations

Information

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
y=a_1+a_2
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, v2, 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:

y=a_1+a_2 (1)

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

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​Figures
Figures

Information

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.
Example 1

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

<img src="../../../../../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="../../../../../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="../../../../../Images/Blocks/PID_controller.png"
           alt="PID_controller.png">
    </td>
  </tr>
</table>

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

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​Hyperlinks
Hyperlinks

Information

  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.
Example 1
<a href="../../../../Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/index.html#PlanarLoops">
         Modelica.Mechanics.MultiBody.UsersGuide.Tutorial.LoopStructures.PlanarLoops</a>

appears as

Modelica.Mechanics.MultiBody.UsersGuide.Tutorial.LoopStructures.PlanarLoops
Example 2
<p>
  The feeder cables are connected to an
  <a href="../../../../Electrical/Machines/BasicMachines/AsynchronousInductionMachines/index.html#AIM_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).

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​Lists
Lists

Information

Lists have to be placed outside of paragraphs to be HTML compliant.

  1. Items of a list shall start with
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

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

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​References
References

Information

General

  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.
Example
<p>
  More details about sensorless rotor temperature estimation
  can be found in <a href="../../UsersGuide/index.html#References">[Gao2008]</a.>
</p>

appears as

More details about sensorless rotor temperature estimation can be found in [Gao2008].

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

Class Modelica.​UsersGuide.​Conventions.​Documentation.​Format.​Tables
Tables

Information

  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.
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

Caption starts with a capital letter
Head 1 Head 2
Entry 1 Entry 2
Entry 3 Entry 4
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

Tab. 2: Caption starts with a capital letter
Head 1 Head 2
Entry 1 Entry 2
Entry 3 Entry 4

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

Generated 2018-12-12 12:09:52 EST by MapleSim.