feat(help): integrate user manual (#249)

ca-d · Jakob Vogelsang · web-flow · commit e5f44706e435 · 2021-07-16T14:53:34.000+02:00
* Initial Home page

* Created DataTypeTemplate editor (markdown)

* Updated DataTypeTemplate editor (markdown)

* Updated DataTypeTemplate editor (markdown)

* Updated DataTypeTemplate editor (markdown)

* Updated DataTypeTemplate editor (markdown)

* Created Guess substation structure (markdown)

* Updated Guess substation structure (markdown)

* Created Importing IEDs (markdown)

* Created _Sidebar (markdown)

* Destroyed _Sidebar (markdown)

* Created Update GOOSE subscriber info in SCL (markdown)

* Created _Sidebar (markdown)

* Created Connect Report Control Blocks with ClientLN (markdown)

* Updated Connect Report Control Blocks with ClientLN (markdown)

* Updated Connect Report Control Blocks with ClientLN (markdown)

* Created Merge functionality (markdown)

* Created How to install OpenSCD offline (markdown)

* Updated How to install OpenSCD offline (markdown)

* Updated How to install OpenSCD offline (markdown)

* Created Manage save project (markdown)

* refactor: remove home screen trick

* feat: add home page with table of content

* fix: ass missing link in table of content

* refactor: add finder-pane for tree nagivation

* typo

* Updated _Sidebar (markdown)

* Add TOC

* Restructure TOC

* feat(help): add offline help browser

Adds an offline wiki markdown explorer based on `finder-pane` in order to let the user find and browse to all help content.

* fix(help): integrate about box in home page

* refactor(package): mark maked types dev dep

* style(help): display help cursor on wiki links

* add editor features section

* Created SCL Sections (markdown)

* add substation page

* add Communication page

* Updated Communication (markdown)

* rename datatypetemplate editor

* add Communication page

* Updated Home (markdown)

* fix(help): fix intra wiki links

* reorder sidebar links

* fix typo

* refactor(help): load manifest.json asynchronously

* refactor(test): remove dead snapshots

* test(help): remove tests until karma loads marked

* test(finder-pane): update snapshot

Co-authored-by: Jakob Vogelsang &lt;jakob.vogelsang@omicronenergy.com&gt;
diff --git a/__snapshots__/enum-type-editor.md b/__snapshots__/enum-type-editor.md
diff --git a/__snapshots__/enum-val-editor.md b/__snapshots__/enum-val-editor.md
diff --git a/__snapshots__/finder-pane.md b/__snapshots__/finder-pane.md
@@ -3,7 +3,7 @@
 #### `displays nothing with default properties`
 
 ```html
-<div>
+<div class="pane">
 </div>
 
 ```
@@ -13,7 +13,7 @@
 ####   `displays one list of children per path entry`
 
 ```html
-<div>
+<div class="pane">
   <section>
     <p>
       e2
@@ -95,7 +95,7 @@
 ####     `appends a new column with the chosen entry's children`
 
 ```html
-<div>
+<div class="pane">
   <section>
     <p>
       e2
@@ -161,7 +161,7 @@
 ####     `replaces all but the first column with a new column`
 
 ```html
-<div>
+<div class="pane">
   <section>
     <p>
       e2
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -39,7 +39,8 @@
     "carehtml": "^0.1.3",
     "lit-element": "2.4.0",
     "lit-html": "1.3.0",
-    "lit-translate": "^1.2.1"
+    "lit-translate": "^1.2.1",
+    "marked": "^2.1.3"
   },
   "scripts": {
     "lint:eslint": "eslint --ext .ts,.html . --ignore-path .gitignore",
@@ -74,6 +75,7 @@
     "@open-wc/testing": "^2.5.33",
     "@open-wc/testing-karma": "^4.0.9",
     "@snowpack/plugin-typescript": "^1.2.1",
+    "@types/marked": "^2.0.4",
     "@types/node": "^15.3.0",
     "@typescript-eslint/eslint-plugin": "^4.24.0",
     "@typescript-eslint/parser": "^4.24.0",
diff --git a/public/md/Communication.md b/public/md/Communication.md
@@ -0,0 +1 @@
+We don't have any help for editing the Communication section yet. If you also find that sad, any contributed documentation is most welcome at https://github.com/openscd/open-scd/wiki/Communication 😅 
diff --git a/public/md/DataTypeTemplates.md b/public/md/DataTypeTemplates.md
@@ -0,0 +1,24 @@
+# Add a `CSWI` functionality logical node template (`LNodeType`) to an empty project
+
+* click the DataTypeTemplate editor tab
+* click the "add LNodeType" button
+* choose "CSWI" from the "lnType" dropdown menu
+* choose possible values for your "ENS" behavior `Beh` enumeration (default all, i.e. `on`, `on-blocked`, `test`, `test-blocked`, `off`)
+  > Enumerations may be assumed zero-indexed unless otherwise noted.
+
+  * choose data attributes for optional substitution services (`subEna`, `subVal`, `subQ`, `subID`, `blkEna`)
+  * choose additional optional data attributes (default none of `d`, `dU`, `cdcName="ENS"`*) *fixed value if selected
+* choose possible values for your "ENC" mode `Mod` enumeration (default all, i.e. `on`, `on-blocked`, `test`, `test-blocked`, `off`)
+  * choose possible values for your "ctlModel" enumeration (default all, i.e. `status-only`, `direct-with-normal-security`, `direct-with-enhanced-security`, `sbo-with-normal-security`, `sbo-with-enhanced-security`)
+  * choose possible originator categories (default all, i.e. `not-supported`, `bay-control`, `station-control`, `remote-control`, `automatic-bay`, `automatic-station`, `automatic-remote`, `maintenance`, `process`)
+  * choose data attributes for control services (`sboTimeout`, `sboClass`, `operTimeout`, `stSeld`, `ctlNum`)
+  * choose data attributes for optional substitution services (`subEna`, `subVal`, `subQ`, `subID`, `blkEna`)
+  * choose remaining optional data attributes (`opRcvd`, `opOk`, `tOpOk`, `d`, `dU`, `cdcName="ENC"`*) *fixed value if selected
+* choose optional data attributes for the "LPL" name plate (`paramRev`, `valRev`, `d`, `dU`, `configRev`, `cdcName="LPL"`*)
+* choose possible values for your "ENS" health `Health` enumeration (default all, i.e. 1. `ok`, 2. `warning`, 3. `alarm`)
+  * choose data attributes for optional substitution services (`subEna`, `subVal`, `subQ`, `subID`, `blkEna`)
+  * choose additional optional data attributes (default none of `d`, `dU`, `cdcName="ENS"`*) *fixed value if selected
+* add a "DPC" position `Pos` double point controllable
+  * choose main data attributes (`ctlModel`, `origin`, `ctlNum`, `stSeld`, `opRcvd`, `opOk`, `tOpOk`, `sboTimeout`, `sboClass`, `operTimeout`, `pulseConfig`)
+  * choose data attributes for optional substitution services (`subEna`, `subVal`, `subQ`, `subID`, `blkEna`)
+  * choose additional optional data attributes (default none of `d`, `dU`, `cdcName="DPC"`*) *fixed value if selected
diff --git a/public/md/Home.md b/public/md/Home.md
@@ -1,30 +1,3 @@
-This is the OpenSCD help. It could be a source for information on topics around IEC 61850-6. You are welcome to share your knowledge with the rest of the world.
+This is an open repository of information on OpenSCD and IEC 61850-6. You are welcome to share your knowledge with the rest of the world at https://github.com/openscd/open-scd/wiki/Home/_edit 😄 . Welcome aboard!
 
-# Table of Contents
-
-## OpenSCD related Topics
-
-- [How to install OpenSCD offline](https://github.com/openscd/open-scd/wiki/How-to-install-OpenSCD-offline)
-- [Manage save project](https://github.com/openscd/open-scd/wiki/Manage-save-project)
-
-## OpenSCD and the IEC 61850-6
-
-### Substation
-
-- [Guess substation structure](https://github.com/openscd/open-scd/wiki/Guess-substation-structure)
-
-### Communication
-
-### IED section
-
-- [Connect Report Control Blocks with ClientLN](https://github.com/openscd/open-scd/wiki/Connect-Report-Control-Blocks-with-ClientLN)
-- [Importing IEDs](https://github.com/openscd/open-scd/wiki/Importing-IEDs)
-- [Update GOOSE subscriber info in SCL](https://github.com/openscd/open-scd/wiki/Update-GOOSE-subscriber-info-in-SCL)
-
-### DataTypeTemplates
-
-- [DataTypeTemplate editor](https://github.com/openscd/open-scd/wiki/DataTypeTemplate-editor)
-
-### Other goodies
-
-- [Merge functionality](https://github.com/openscd/open-scd/wiki/Merge-functionality)
+So far we have documented some essential [general OpenSCD editor features](https://github.com/openscd/open-scd/wiki/OpenSCD-Editor-Features) and features regarding the individual [sections of an SCL file](https://github.com/openscd/open-scd/wiki/SCL-Sections) .
diff --git a/public/md/IED.md b/public/md/IED.md
@@ -0,0 +1 @@
+Here you may learn how to [Connect Report Control Blocks with ClientLN nodes](https://github.com/openscd/open-scd/wiki/Connect-Report-Control-Blocks-with-ClientLN), how to [Import IEDs](https://github.com/openscd/open-scd/wiki/Importing-IEDs) into a project, and how to [Update the GOOSE subscriber info in your SCL file](https://github.com/openscd/open-scd/wiki/Update-GOOSE-subscriber-info-in-SCL).
diff --git a/public/md/OpenSCD-Editor-Features.md b/public/md/OpenSCD-Editor-Features.md
@@ -0,0 +1,2 @@
+Here you can find a help page describing how to [install OpenSCD offline](https://github.com/openscd/open-scd/wiki/How-to-install-OpenSCD-offline) and
+pages related to **Project Management** explaining how to [save an SCL file](https://github.com/openscd/open-scd/wiki/Manage-save-project) and [merge an SCL file](https://github.com/openscd/open-scd/wiki/Merge-functionality) into an already opened project.
diff --git a/public/md/SCL-Sections.md b/public/md/SCL-Sections.md
@@ -0,0 +1 @@
+The major sections of the SCL file you may want to edit are the [Substation section](https://github.com/openscd/open-scd/wiki/Substation), the [Communication section](https://github.com/openscd/open-scd/wiki/Communication), the [IED section](https://github.com/openscd/open-scd/wiki/IED), and the [DataTypeTemplates section](https://github.com/openscd/open-scd/wiki/DataTypeTemplates)
diff --git a/public/md/Substation.md b/public/md/Substation.md
@@ -0,0 +1 @@
+The Substation Editor has the ability to [Guess substation structure](https://github.com/openscd/open-scd/wiki/Guess-substation-structure) from an SCL file containing IEDs and a Data Model but no ready Substation section.
diff --git a/public/md/_Sidebar.md b/public/md/_Sidebar.md
@@ -2,6 +2,7 @@
 
 - [How to install OpenSCD offline](https://github.com/openscd/open-scd/wiki/How-to-install-OpenSCD-offline)
 - [Manage save project](https://github.com/openscd/open-scd/wiki/Manage-save-project)
+- [Merge two projects](https://github.com/openscd/open-scd/wiki/Merge-functionality)
 
 ## SCL Sections
 
@@ -20,7 +21,3 @@
 ### DataTypeTemplates
 
 - [DataTypeTemplate editor](https://github.com/openscd/open-scd/wiki/DataTypeTemplate-editor)
-
-### All sections
-
-- [Merge functionality](https://github.com/openscd/open-scd/wiki/Merge-functionality)
diff --git a/src/finder-pane.ts b/src/finder-pane.ts
@@ -93,11 +93,13 @@ export class FinderPane extends LitElement {
       this.renderDirectory(parent, index)
     );
     this.loaded = Promise.allSettled(lists).then();
-    return html`<div>${lists.map(list => until(list, waitingList))}</div>`;
+    return html`<div class="pane">
+      ${lists.map(list => until(list, waitingList))}
+    </div>`;
   }
 
   static styles = css`
-    div {
+    div.pane {
       display: flex;
       flex-direction: row;
       overflow: auto;
@@ -116,5 +118,21 @@ export class FinderPane extends LitElement {
     section > mwc-list {
       margin-top: 76px;
     }
+
+    a {
+      font-weight: 600;
+      font-variant: small-caps;
+      text-transform: lowercase;
+      text-decoration: none;
+      color: var(--mdc-theme-primary);
+    }
+
+    a:link {
+      color: var(--mdc-theme-error);
+    }
+
+    a:visited {
+      color: var(--mdc-theme-secondary);
+    }
   `;
 }
diff --git a/src/menu/Help.ts b/src/menu/Help.ts
@@ -1,43 +1,73 @@
 import { html, LitElement } from 'lit-element';
+import { unsafeHTML } from 'lit-html/directives/unsafe-html';
+
+import marked from 'marked';
 
 import { newWizardEvent, Wizard } from '../foundation.js';
 import { openSCDIcon } from '../icons.js';
 
-import additionInfo from '../../manifest.json';
+import { Directory } from '../finder-pane.js';
+
+function aboutBox(version: string) {
+  return html`<div>
+      <div style="display:flex">
+        <mwc-icon slot="graphic" style="--mdc-icon-size:25px"
+          >${openSCDIcon}</mwc-icon
+        >
+        <div style="padding:10px">
+          <h2 style="margin-bottom:2px">OpenSCD</h2>
+          V${version}
+        </div>
+      </div>
+    </div>
+    <div>
+      <h3>Licences</h3>
+      <p style="padding-bottom:5px">
+        The IEC&thinsp;61850 XSD and NSD code components used are distributed
+        under their
+        <a href="/CC-EULA.pdf">end user licence agreement</a>. <br />This
+        project's source code is licensed under the
+        <a href="/LICENSE.md">Apache&thinsp;2.0 license</a> and available on
+        <a href="https://github.com/openscd">GitHub</a>.
+      </p>
+      <p>&copy; 2020-2021 OMICRON electronics GmbH</p>
+      <h3>Help</h3>
+    </div>`;
+}
+
+async function getLinkedPages(path: string[]): Promise<Directory> {
+  const edition = await (await fetch('/manifest.json')).json();
+  if (path.length === 0) {
+    return { content: aboutBox(edition.version), children: ['Home'] };
+  }
+
+  const page = path[path.length - 1].replace(/ /g, '-');
+  const res = await fetch(`/public/md/${page}.md`);
+  const md = await res.text();
+  const unlinkedMd = md.replace(
+    /\[([^\]]*)\]\(https:..github.com.openscd.open-scd.wiki.([^)]*)\)/g,
+    `<a style="cursor: help;" onclick="Array.from(event.target.closest('section').lastElementChild.children).find(child => child.text === '$2'.replace(/-/g, ' ')).click()">$1</a>`
+  );
+  const content = html`<div style="padding: 8px;">
+    ${page === 'Home' ? aboutBox(edition.version) : html``}
+    ${unsafeHTML(marked(unlinkedMd))}
+  </div>`;
+  const children = Array.from(
+    md.matchAll(/\(https:..github.com.openscd.open-scd.wiki.([^)]*)\)/g)
+  ).map(([_, child]) => child.replace(/-/g, ' '));
+
+  return { content, children };
+}
 
 export function aboutBoxWizard(): Wizard {
   return [
     {
       title: 'Help',
       content: [
-        html`<div>
-            <div style="display:flex">
-              <mwc-icon slot="graphic" style="--mdc-icon-size:25px"
-                >${openSCDIcon}</mwc-icon
-              >
-              <div style="padding:10px">
-                <h2 style="margin-bottom:2px">OpenSCD</h2>
-                V${additionInfo.version}
-              </div>
-            </div>
-          </div>
-          <div>
-            <h4>Licences</h4>
-            <p style="padding-bottom:5px">
-              The IEC&thinsp;61850 XSD and NSD code components used are
-              distributed under their
-              <a href="/CC-EULA.pdf">end user licence agreement</a>. <br />This
-              project is licensed under the
-              <a href="/LICENSE.md">Apache&thinsp;2.0</a>.
-            </p>
-            <h4>Help</h4>
-            <p>
-              <a href="https://github.com/openscd/open-scd/wiki/"
-                >OpenSCD wiki</a
-              >
-            </p>
-            <p>&copy; 2020-2021 OMICRON electronics GmbH</p>
-          </div>`,
+        html`<finder-pane
+          .path=${['Home']}
+          .getChildren=${getLinkedPages}
+        ></finder-pane>`,
       ],
     },
   ];
diff --git a/test/integration/menu/HelpPlugin.test.ts b/test/integration/menu/HelpPlugin.test.ts
diff --git a/test/integration/menu/NewProject.test.ts b/test/integration/menu/NewProject.test.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+We don't have any help for editing the Communication section yet. If you also find that sad, any contributed documentation is most welcome at https://github.com/openscd/open-scd/wiki/Communication 😅`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Here you may learn how to [Connect Report Control Blocks with ClientLN nodes](https://github.com/openscd/open-scd/wiki/Connect-Report-Control-Blocks-with-ClientLN), how to [Import IEDs](https://github.com/openscd/open-scd/wiki/Importing-IEDs) into a project, and how to [Update the GOOSE subscriber info in your SCL file](https://github.com/openscd/open-scd/wiki/Update-GOOSE-subscriber-info-in-SCL).`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Here you can find a help page describing how to [install OpenSCD offline](https://github.com/openscd/open-scd/wiki/How-to-install-OpenSCD-offline) and`
	`2`	`+pages related to Project Management explaining how to [save an SCL file](https://github.com/openscd/open-scd/wiki/Manage-save-project) and [merge an SCL file](https://github.com/openscd/open-scd/wiki/Merge-functionality) into an already opened project.`