Merge pull request #77 from modelica/feature/add-ls-bus-guide

Add initial empty LS-BUS guide

.github/workflows/build-guides.yml

@@ -16,23 +16,33 @@ jobs:
     - name: checkout
       uses: actions/checkout@v3
     - name: prepare
-      run: mkdir build && mkdir build/fmi-guide && mkdir build/fmi-profiles
+      run: mkdir build && mkdir build/fmi-guide && mkdir build/ls-bus-guide && mkdir build/fmi-profiles
     - name: build implementers guide
       uses: avattathil/asciidoctor-action@master
       with:
         program: "asciidoctor -D build/fmi-guide --backend=html5 --attribute=revnumber=${GITHUB_REF#refs/heads/}-$GITHUB_SHA --attribute=revdate=$(date +%F) fmi-guide/index.adoc"
+    - name: build LS-BUS implementers guide
+      uses: avattathil/asciidoctor-action@master
+      with:
+        program: "asciidoctor -D build/ls-bus-guide --backend=html5 --attribute=revnumber=${GITHUB_REF#refs/heads/}-$GITHUB_SHA --attribute=revdate=$(date +%F) ls-bus-guide/index.adoc"
     - name: build FMI profiles
       uses: avattathil/asciidoctor-action@master
       with:
         program: "asciidoctor -D build/fmi-profiles --backend=html5 --attribute=revnumber=${GITHUB_REF#refs/heads/}-$GITHUB_SHA --attribute=revdate=$(date +%F) fmi-profiles/index.adoc"
     - name: copy images
-      run: tar cf - fmi-guide/images fmi-profiles/images | tar xfC - build
+      run: tar cf - fmi-guide/images ls-bus-guide/images fmi-profiles/images | tar xfC - build
     - name: archive implementers guide
       uses: actions/upload-artifact@v3
       with:
         name: FMI-Guide
         path: build/fmi-guide/*
         if-no-files-found: error
+    - name: archive LS-BUS implementers guide
+      uses: actions/upload-artifact@v3
+      with:
+        name: LS-BUS-Guide
+        path: build/ls-bus-guide/*
+        if-no-files-found: error
     - name: archive FMI profiles
       uses: actions/upload-artifact@v3
       with:

README.md

@@ -3,10 +3,10 @@
 [![Build Specification](https://github.com/modelica/fmi-guides/actions/workflows/build-guides.yml/badge.svg)](https://github.com/modelica/fmi-guides/actions/workflows/build-guides.yml)
 
 This repository contains a number of  current prototype draft guides
-for the current [Functional Mock-up Interface][FMI] 2.0 and upcoming
-3.0 standard for the exchange of simulation models. Note that these
-drafts are being worked on actively, and thus are subject to change
-without notice.
+for the current [Functional Mock-up Interface][FMI] 3.0 standard for
+the exchange of simulation models, as well as upcoming layered
+standards on top of it. Note that these drafts are being worked on
+actively, and thus are subject to change without notice.
 
 They are not normative, nor are they to be considered officially
 endorsed by the Modelica Association or other involved organisations
@@ -16,13 +16,21 @@ The [FMI 3.0 Implementer's Guide][guide] is currently maintained on
 [GitHub][githubguide] and is published [here][guide]. It is based on
 the [FMI][] standard.
 
+The [FMI LS BUS Implementer's Guide][ls-bus-guide] is currently
+maintained on [GitHub][github-ls-bus-guide] and is published
+[here][ls-bus-guide]. It is based on the [FMI-LS-BUS][] layered
+standard for Network Communication.
+
 The [FMI 2.0/3.0 Profiles][profile] are currently maintained on
 [GitHub][githubprofile] and is published [here][profile].
 
 In future additional guides might be integrated into this repository.
 
 [FMI]: https://fmi-standard.org/
+[FMI-LS-BUS]: https://github.com/modelica/fmi-ls-bus/
 [githubguide]: fmi-guide/index.adoc
 [guide]: https://modelica.github.io/fmi-guides/main/fmi-guide/
+[github-ls-bus-guide]: ls-bus-guide/index.adoc
+[ls-bus-guide]: https://modelica.github.io/fmi-guides/main/ls-bus-guide/
 [githubprofile]: fmi-profiles/index.adoc
 [profile]: https://modelica.github.io/fmi-guides/main/fmi-profiles/

ls-bus-guide/0___preamble.adoc

@@ -0,0 +1,18 @@
+The FMI LS Bus Implementers' Guide is a free resource intended to give non-normative recommendations and guidance to implementers of the Functional Mock-up Interface layered standard Network Communication (FMI-LS-BUS).
+This document is continually revised based on implementer and user feedback and input.
+All of the content is to be considered non-normative and shall not be considered to supplant any normative statement in the FMI 3.0 standard, the FMI-LS-BUS layered standard, or any other standard or layered standard.
+https://github.com/modelica/fmi-guides/releases[Releases] and https://github.com/modelica/fmi-guides/issues[issues] can be found on https://github.com/modelica/fmi-guides[github.com/modelica/fmi-guides].
+
+{empty} +
+{empty}
+
+Copyright (C) 2021-2023 The Modelica Association Project FMI.
+
+This document is licensed under the Attribution-ShareAlike 4.0 International license.
+The code is released under the 2-Clause BSD License.
+The licenses text can be found in the https://raw.githubusercontent.com/modelica/fmi-guides/main/LICENSE.txt[LICENSE.txt] file that accompanies this distribution.
+
+Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights.
+Modelica Association shall not be held responsible for identifying such patent rights.
+
+{empty}

ls-bus-guide/1___introduction.adoc

@@ -0,0 +1,3 @@
+== Introduction
+
+TODO

ls-bus-guide/A___literature.adoc

@@ -0,0 +1,6 @@
+[bibliography]
+== References
+
+- [[[RFC2119]]] Bradner, S.: **Key words for use in RFCs to Indicate Requirement Levels**. RFC 2119, March 1997. https://www.ietf.org/rfc/rfc2119.txt
+
+- [[[SEMVER200]]] Preston-Werner, T.: **Semantic Versioning 2.0.0**. https://semver.org/spec/v2.0.0.html

ls-bus-guide/README.md

@@ -0,0 +1,20 @@
+# FMI LS BUS Implementers' Guide
+
+[![Build Specification](https://github.com/modelica/fmi-guides/actions/workflows/build-guides.yml/badge.svg)](https://github.com/modelica/fmi-guides/actions/workflows/build-guides.yml)
+
+This directory contains the current prototype draft Implementers'
+Guide for the upcoming [FMI-LS-BUS][FMI-LS-BUS] layered standard for
+the exchange of simulation models employing bus communication.  Note
+that this draft is being worked on actively, and thus subject to change
+without notice.
+
+It is not normative, nor is it to be considered officially endorsed
+by the Modelica Association prior to official adoption.
+
+The [guide][] is currently maintained on [GitHub][github] and is
+published [here][guide]. It is based on the [FMI-LS-BUS][] layered
+standard.
+
+[FMI-LS-BUS]: https://github.com/modelica/fmi-ls-bus/
+[github]: index.adoc
+[guide]: https://modelica.github.io/fmi-guides/main/ls-bus-guide/

ls-bus-guide/docinfo.html

@@ -0,0 +1,102 @@
+<script>
+// hide / show the Table of Contents (TOC)
+function toggleTOC() {
+  var toc = document.getElementById("toc");
+  var body = document.getElementsByTagName("body")[0];
+
+  if (toc.style.display === "none") {
+      toc.style.display = "block";
+      body.classList.remove("toc-hidden");
+  } else {
+      toc.style.display = "none";
+      body.classList.add("toc-hidden");
+  }
+}
+
+// toggle the TOC when "t" key is pressed
+document.addEventListener('keydown', (event) => {
+  if (event.key == 't') {
+    toggleTOC();
+  }
+});
+</script>
+
+<!-- Generate a nice TOC -->
+<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
+<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/javascripts/jquery.tocify.min.js"></script>
+<!-- We do not need the tocify CSS because the asciidoc CSS already provides most of what we neeed -->
+
+<style>
+.tocify-header {
+    font-style: italic;
+}
+
+.tocify-subheader {
+    font-style: normal;
+    font-size: 90%;
+}
+
+.tocify ul {
+    margin: 0;
+ }
+
+.tocify-focus {
+    color: #7a2518;
+    background-color: rgba(0, 0, 0, 0.1);
+}
+
+.tocify-focus > a {
+    color: #7a2518;
+}
+</style>
+
+<script type="text/javascript">
+    $(function () {
+        // Add a new container for the tocify toc into the existing toc so we can re-use its
+        // styling
+        $("#toc").append("<div id='generated-toc'></div>");
+        $("#generated-toc").tocify({
+            extendPage: true,
+            context: "#content",
+            highlightOnScroll: true,
+            // don't hide the sections in the TOC
+            showAndHide: false,
+            hideEffect: "slideUp",
+            // Use the IDs that asciidoc already provides so that TOC links and intra-document
+            // links are the same. Anything else might confuse users when they create bookmarks.
+            hashGenerator: function(text, element) {
+                return $(element).attr("id");
+            },
+            // Smooth scrolling doesn't work properly if we use the asciidoc IDs
+            smoothScroll: false,
+            // Set to 'none' to use the tocify classes
+            theme: "none",
+            // Handle book (may contain h1) and article (only h2 deeper)
+            selectors: $( "#content" ).has( "h1" ).size() > 0 ? "h1,h2,h3" : "h2,h3,h4",
+            ignoreSelector: ".discrete"
+        });
+
+        // Switch between static asciidoc toc and dynamic tocify toc based on browser size
+        // This is set to match the media selectors in the asciidoc CSS
+        // Without this, we keep the dynamic toc even if it is moved from the side to preamble
+        // position which will cause odd scrolling behavior
+        var handleTocOnResize = function() {
+            if ($(document).width() < 768) {
+                $("#generated-toc").hide();
+                $(".sectlevel0").show();
+                $(".sectlevel1").show();
+            }
+            else {
+                $("#generated-toc").show();
+                $(".sectlevel0").hide();
+                $(".sectlevel1").hide();
+            }
+        }
+
+        $(window).resize(handleTocOnResize);
+        handleTocOnResize();
+    });
+</script>
+
+<img style="display: block; margin: 2em auto; width: 30em;" src="images/FMI_logo_horizontal.svg" alt="FMI logo">