Skip to content

Conventions for Examples

Jump to bottom
Rainer Klute edited this page May 15, 2017 · 13 revisions

You want to create and submit your own example? Great! While doing so, please stick to the following conventions:

Example Directory

Each example must reside in a directory of its own within the repository's root directory. Please choose a descriptive directory name! It must be lower case with words separated by underscores.

  • Example: coffee_machine

Description

An example should have a description. The documentation must be in HTML, and it must be in a file named index.html on the top level of your example directory.

  • Example: coffee_machine/index.html

Please use the following HTML code as a template for your index.html file and modify it as needed. However, please make sure to leave the outer frame intact. What you should change is

  • the title, i.e. the text between <title> and </title> and
  • the actual contents, i.e. the text between <div class="primary"> and the associated </div> near the end.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>The Example's Title Goes Here</title>
<link href="../css/style.css" rel="stylesheet">
</head>
<body class="body-container">
  <div class="primary">

    <h1>The Example's Title Goes Here</h1>

    <p>The example's description goes here in HTML format.
      You can use images like this one:</p>

    <p>
      <img class="standard-image" alt="The state machine"
        src="images/the_state_machine.png" />
    </p>

  </div>
</body>
</html>

Image Directory

Images must be contained in a directory named images.

  • Example: coffee_machine/images/the_state_machine.png

Model Directory

State machine models should be contained in a directory named model.

  • Example: coffee_machine/model/coffee_machine_01.sct

Names of Files and Directories

Names of example directories must be lower case with words separated by underscores. Files within example directories and subordinate directories should follow the same naming convention.

  • Example: this_is_a_good_title
  • Counterexample: ThisIs-Not-a_good_Title

Example Title

An example must have a title which should describe the example as concise as possible. The title should be capitalized properly, for example This is a Suitable Title. If unsure which words to capitalize or not, these capitalization rules for titles are helpful.

The title must occur identically at the following places:

  • as the <title> element in the index.html file,
  • as the first (and only) <h1> element in the index.html file,
  • as the title attribute in the metadata.json file.

No Generated Artifacts in the Repository

Generated artifacts, like C or Java sources produced by a code generator or binaries produced by a compiler do no belong into the repository. If any manual steps are needed to reproduce such artifacts, please describe them in your example's documentation, i. e. in the index.html file.

Clone this wiki locally