update index, add rationale, improve getting started

Author: bjornregnell

index.html

@@ -99,36 +99,40 @@ <h1 class="title">reqT - Requirements Engineering Tool</h1>
 </header>
 <nav id="TOC" role="doc-toc">
 <ul>
+<li><a href="#what-is-reqt" id="toc-what-is-reqt">What is reqT?</a></li>
 <li><a href="#download" id="toc-download">Download</a></li>
 <li><a href="#getting-started" id="toc-getting-started">Getting
 started</a></li>
 <li><a href="#why-reqt" id="toc-why-reqt">Why reqT?</a></li>
-<li><a href="#using-the-reqt-app" id="toc-using-the-reqt-app">Using the
-reqT App</a></li>
+<li><a href="#using-the-reqt-desktop-app"
+id="toc-using-the-reqt-desktop-app">Using the reqT desktop app</a></li>
 <li><a href="#using-reqt-with-scala"
 id="toc-using-reqt-with-scala">Using reqT with Scala</a></li>
 <li><a href="#publications" id="toc-publications">Publications</a></li>
 </ul>
 </nav>
+<h2 id="what-is-reqt">What is reqT?</h2>
 <p><strong>reqT</strong> is an open source requirements engineering tool
-for software developers based on <strong>reqT-lang</strong>, a flexible
-requirements modelling language with essential requirements engineering
+for software developers and learners, available as a desktop application
+and a Scala library. With reqT you can specify requirements using a
+flexible requirements modelling language called
+<strong>reqT-lang</strong> with essential requirements engineering
 concepts, giving structure to natural language requirements, while
 enabling analysis, visualization and automation.</p>
-<p>The <strong>reqT-lang syntax</strong> is a subset of Markdown using
-bullet lists with indentation and special keywords to express textual
-requirements models by connecting <em>entities</em>, such as a <span
-class="EntType">Feature</span>, with <em>relations</em>, such as <span
-class="RelType">has</span>, to <em>attributes</em>, such as <span
-class="StrAttrType">Spec</span>, as in the example below:</p>
+<p>The reqT-lang syntax is a small subset of <a
+href="https://en.wikipedia.org/wiki/Markdown">Markdown</a> using bullet
+lists with indentation and special keywords, to express textual
+requirements models by connecting <span
+class="EntType"><em>entities</em></span> via <span
+class="RelType"><em>relations</em></span> to <span
+class="StrAttrType"><em>attributes</em></span>, as in this example:</p>
 <pre><code>* <span class="EntType">Feature</span>: helloWorld <span class="RelType">has</span> 
   * <span class="StrAttrType">Spec</span>: Print a nice greeting.
   * <span class="StrAttrType">Why</span>: First step to get started.
 </code></pre>
-<p>See the
+<p>Visit the
 <a href="https://github.com/reqT/reqT-lang/releases/latest/download/reqT-quickref-GENERATED.pdf"><strong>Quickref</strong></a>
-to explore reqT keywords covering essential requirements engineering
-concepts.</p>
+to explore requirements engineering concepts of reqT.</p>
 <p>Maintainer of reqT: <a
 href="https://cs.lth.se/bjorn-regnell">Prof. Björn Regnell</a>. Used at
 Lund University in <a href="https://cs.lth.se/krav">this course</a>.</p>
@@ -165,46 +169,55 @@ <h2 id="getting-started">Getting started</h2>
 <ul>
 <li><p>Make sure you have <a
 href="https://adoptium.net/temurin/releases/?package=jdk&amp;version=21">Java
-21</a> and <a href="https://www.scala-lang.org/download/">Scala 3</a>
-installed for your system. Check this in terminal using:
-</br><code>java -version</code></br><code>scala -version</code></p></li>
+21 - LTS</a> and <a href="https://www.scala-lang.org/download/">Scala
+3</a> installed for your system. Check this in terminal using:
+</br><code>java -version</code></br><code>scala -version</code></br> (If
+you use later versions than Java 21 - LTS and Scala 3.6.4 you may get
+some warnings, but things should work fine anyway.)</p></li>
 <li><p>Download the <a
 href="https://github.com/reqT/reqT/releases/latest/download/reqT.jar">reqT
 desktop app</a> and run in terminal using:
 <code>java -jar reqT.jar</code></p></li>
+<li><p>Visit the reqT <a
+href="https://github.com/reqT/reqT-lang/releases/latest/download/reqT-quickref-GENERATED.pdf">Quickref</a>
+to learn about available concepts in reqT-lang.</p></li>
 <li><p>Learn more about <a href="#using-the-reqt-app">using the reqT
 app</a></p></li>
+<li><p>Do the reqT labs to learn about using reqT in Requirements
+Engineering:</p>
+<ul>
+<li><a href="https://github.com/reqT/reqT/blob/4.x/docs/lab1.md">Lab 1:
+Context, Features and Priorities</a></li>
+<li><a href="https://github.com/reqT/reqT/blob/4.x/docs/lab2.md">Lab 2:
+Quality Requirements and Release Planning</a></li>
+<li>Labs are part of this course at Lund University: <a
+href="https://lunduniversity.github.io/krav/">ETSN15 Requirements
+Eng.</a></li>
+</ul></li>
 <li><p>Start reqT in the <a
 href="https://docs.scala-lang.org/scala3/book/taste-repl.html">Scala
-REPL</a> using: <code>java -jar reqT.jar repl</code></p></li>
+REPL</a> using: <code>java -jar reqT.jar repl</code> </br> You can
+create a requirements Model in the scala repl like so:</p></li>
 </ul>
-<pre><code>$ java -jar reqT.jar repl
-
-Welcome to reqT 4.5.6 https://reqT.github.io
-Type &#39;edit&#39; to open a new reqT window.
-Type &#39;:quit&#39; or press Ctrl+D to exit.
-Re-run with -h for help on main program args
-
-scala repl -S 3.6.4-RC1 --jar reqT.jar -- --repl-init-script &quot;import reqt.*&quot;
-Welcome to Scala 3.6.4-RC1 (17.0.13, Java OpenJDK 64-Bit Server VM).
-Type in expressions for evaluation. Or try :help.
-
-scala&gt; val m = &quot;* Feature: helloWorld has Spec: print greeting&quot;.toModel
-val m: reqt.Model = 
-  Model(Rel(Ent(Feature,helloWorld),Has,
-    Model(StrAttr(Spec,print greeting))))
-
-scala&gt; println(m.show)
-Model(
-  Feature(&quot;helloWorld&quot;) has Spec(&quot;print greeting&quot;),
-)
-</code></pre>
+<div class="sourceCode" id="cb1"><pre
+class="sourceCode scala"><code class="sourceCode scala"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>scala<span class="op">&gt;</span> <span class="kw">val</span> m <span class="op">=</span> <span class="st">&quot;* Feature: helloWorld has Spec: print greeting&quot;</span><span class="op">.</span>toModel</span>
+<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="kw">val</span> m<span class="op">:</span> reqt<span class="op">.</span>Model <span class="op">=</span> </span>
+<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>  <span class="fu">Model</span><span class="op">(</span><span class="fu">Rel</span><span class="op">(</span><span class="fu">Ent</span><span class="op">(</span>Feature<span class="op">,</span>helloWorld<span class="op">),</span>Has<span class="op">,</span></span>
+<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a>    <span class="fu">Model</span><span class="op">(</span><span class="fu">StrAttr</span><span class="op">(</span>Spec<span class="op">,</span>print greeting<span class="op">))))</span></span>
+<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>scala<span class="op">&gt;</span> <span class="fu">println</span><span class="op">(</span>m<span class="op">.</span>show<span class="op">)</span></span>
+<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="fu">Model</span><span class="op">(</span></span>
+<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a>  <span class="fu">Feature</span><span class="op">(</span><span class="st">&quot;helloWorld&quot;</span><span class="op">)</span> has <span class="fu">Spec</span><span class="op">(</span><span class="st">&quot;print greeting&quot;</span><span class="op">),</span></span>
+<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a><span class="op">)</span></span></code></pre></div>
 <ul>
-<li>You can use reqT as a library in Scala programs for specification
-analysis and automation. Download example below here: <a
+<li>You can use reqT in Scala programs for automated requirements
+analysis.
+<ul>
+<li>Download example: <a
 href="https://github.com/reqT/reqT.github.io/blob/master/src/hello-reqt.scala"><code>hello-reqt.scala</code></a>
 and run in terminal using: <br>
 <code>scala run hello-reqt.scala</code></li>
+</ul></li>
 </ul>
 <div class="sourceCode" id="cb2"><pre
 class="sourceCode scala"><code class="sourceCode scala"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="co">//&gt; using scala 3.6.4</span></span>
@@ -222,14 +235,26 @@ <h2 id="getting-started">Getting started</h2>
 <span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a>@main <span class="kw">def</span> hello <span class="op">=</span> </span>
 <span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a>  <span class="fu">println</span><span class="op">(</span>m<span class="op">.</span>toMarkdown<span class="op">)</span></span></code></pre></div>
 <h2 id="why-reqt">Why reqT?</h2>
-<ul>
-<li>TODO: add rationale for requirements as code from old site here: <a
-href="https://reqt.org/index.html">reqt.org</a></li>
-</ul>
-<h2 id="using-the-reqt-app">Using the reqT App</h2>
-<ul>
-<li>TODO: more screendumps and explanations</li>
-</ul>
+<p>With reqT you can…</p>
+<ol type="1">
+<li>Model, analyse, visualize and prioritize requirements.</li>
+<li>Combine natural language with formal structure.</li>
+<li>Flexibly mix abstraction levels and modelling approaches.</li>
+<li>Integrate requirements and test specification.</li>
+<li>Export and import models via open formats.</li>
+<li>Manipulate models with expressive, safe and convenient Scala
+programs.</li>
+<li>Allocate requirements to releases with constraint solving.</li>
+<li>Express prompts for spec-driven development with generative AI
+.</li>
+</ol>
+<p>… using a simple markdown-based language in an open source tool and
+library.</p>
+<h2 id="using-the-reqt-desktop-app">Using the reqT desktop app</h2>
+<p>Download <a
+href="https://github.com/reqT/reqT/releases/latest/download/reqT.jar">reqT.jar</a>
+and start by double-click or open a terminal and navigate to the folder
+with the downloaded file and type: <code>java -jar reqT.jar</code></p>
 <figure>
 <img src="img/screen1.png" alt="reqT Main Window" />
 <figcaption aria-hidden="true">reqT Main Window</figcaption>

src/index-GENERATED.md

@@ -1,13 +1,15 @@
-**reqT** is an open source requirements engineering tool for software developers based on **reqT-lang**, a flexible requirements modelling language with essential requirements engineering concepts, giving structure to natural language requirements, while enabling analysis, visualization and automation. 
+## What is reqT?
 
-The **reqT-lang syntax** is a subset of Markdown using bullet lists with indentation and special keywords to express textual requirements models by connecting *entities*, such as a <span class="EntType">Feature</span>, with *relations*, such as <span class="RelType">has</span>, to *attributes*, such as <span class="StrAttrType">Spec</span>, as in the example below:
+**reqT** is an open source requirements engineering tool for software developers and learners, available as a desktop application and a Scala library.  With reqT you can specify requirements using a flexible requirements modelling language called **reqT-lang** with essential requirements engineering concepts, giving structure to natural language requirements, while enabling analysis, visualization and automation. 
+
+The reqT-lang syntax is a small subset of [Markdown](https://en.wikipedia.org/wiki/Markdown) using bullet lists with indentation and special keywords, to express textual requirements models by connecting <span class="EntType">*entities*</span> via <span class="RelType">*relations*</span> to <span class="StrAttrType">*attributes*</span>, as in this example:
 
 <pre><code>* <span class="EntType">Feature</span>: helloWorld <span class="RelType">has</span> 
   * <span class="StrAttrType">Spec</span>: Print a nice greeting.
   * <span class="StrAttrType">Why</span>: First step to get started.
 </code></pre>
 
-See the <a href="https://github.com/reqT/reqT-lang/releases/latest/download/reqT-quickref-GENERATED.pdf">**Quickref**</a> to explore reqT keywords covering essential requirements engineering concepts.
+Visit the <a href="https://github.com/reqT/reqT-lang/releases/latest/download/reqT-quickref-GENERATED.pdf">**Quickref**</a> to explore requirements engineering concepts of reqT.
 
 Maintainer of reqT: [Prof. Björn Regnell](https://cs.lth.se/bjorn-regnell). 
 Used at Lund University in [this course](https://cs.lth.se/krav). 
@@ -48,26 +50,22 @@ Latest version: <b>
 
 
 ## Getting started
-* Make sure you have [Java 21](https://adoptium.net/temurin/releases/?package=jdk&version=21) and [Scala 3](https://www.scala-lang.org/download/) installed for your system. Check this in terminal using: </br>`java -version`</br>`scala -version`
+* Make sure you have [Java 21 - LTS](https://adoptium.net/temurin/releases/?package=jdk&version=21) and [Scala 3](https://www.scala-lang.org/download/) installed for your system. Check this in terminal using: </br>`java -version`</br>`scala -version`</br> (If you use later versions than Java 21 - LTS and Scala 3.6.4 you may get some warnings, but things should work fine anyway.)
 
 * Download the [reqT desktop app](https://github.com/reqT/reqT/releases/latest/download/reqT.jar) and run in terminal using: `java -jar reqT.jar` 
 
-* Learn more about [using the reqT app](#using-the-reqt-app)
-
-* Start reqT in the [Scala REPL](https://docs.scala-lang.org/scala3/book/taste-repl.html) using: `java -jar reqT.jar repl`
+* Visit the reqT [Quickref](https://github.com/reqT/reqT-lang/releases/latest/download/reqT-quickref-GENERATED.pdf) to learn about available concepts in reqT-lang.
 
-```
-$ java -jar reqT.jar repl
+* Learn more about [using the reqT app](#using-the-reqt-app)
 
-Welcome to reqT 4.5.6 https://reqT.github.io
-Type 'edit' to open a new reqT window.
-Type ':quit' or press Ctrl+D to exit.
-Re-run with -h for help on main program args
+* Do the reqT labs to learn about using reqT in Requirements Engineering:
+  * [Lab 1: Context, Features and Priorities](https://github.com/reqT/reqT/blob/4.x/docs/lab1.md) 
+  * [Lab 2: Quality Requirements and Release Planning](https://github.com/reqT/reqT/blob/4.x/docs/lab2.md)
+  * Labs are part of this course at Lund University: [ETSN15 Requirements Eng.](https://lunduniversity.github.io/krav/) 
 
-scala repl -S 3.6.4-RC1 --jar reqT.jar -- --repl-init-script "import reqt.*"
-Welcome to Scala 3.6.4-RC1 (17.0.13, Java OpenJDK 64-Bit Server VM).
-Type in expressions for evaluation. Or try :help.
+* Start reqT in the [Scala REPL](https://docs.scala-lang.org/scala3/book/taste-repl.html) using: `java -jar reqT.jar repl` </br> You can create a requirements Model in the scala repl like so:
 
+```scala
 scala> val m = "* Feature: helloWorld has Spec: print greeting".toModel
 val m: reqt.Model = 
   Model(Rel(Ent(Feature,helloWorld),Has,
@@ -79,7 +77,8 @@ Model(
 )
 
 ```
-* You can use reqT as a library in Scala programs for specification analysis and automation. Download example below here: [`hello-reqt.scala`](https://github.com/reqT/reqT.github.io/blob/master/src/hello-reqt.scala) and run in terminal using: <br> `scala run hello-reqt.scala`  
+* You can use reqT in Scala programs for automated requirements analysis. 
+  * Download example: [`hello-reqt.scala`](https://github.com/reqT/reqT.github.io/blob/master/src/hello-reqt.scala) and run in terminal using: <br> `scala run hello-reqt.scala`  
 
 ```scala
 //> using scala 3.6.4
@@ -100,11 +99,22 @@ val m = Model(
 
 ## Why reqT?
 
-* TODO: add rationale for requirements as code from old site here: [reqt.org](https://reqt.org/index.html)
+With reqT you can...
+
+1. Model, analyse, visualize and prioritize requirements.
+1. Combine natural language with formal structure.
+1. Flexibly mix abstraction levels and modelling approaches.
+1. Integrate requirements and test specification.
+1. Export and import models via open formats.
+1. Manipulate models with expressive, safe and convenient Scala programs.
+1. Allocate requirements to releases with constraint solving.
+1. Express prompts for spec-driven development with generative AI .
+
+... using a simple markdown-based language in an open source tool and library.
 
-## Using the reqT App
+## Using the reqT desktop app
 
-* TODO: more screendumps and explanations
+Download [reqT.jar](https://github.com/reqT/reqT/releases/latest/download/reqT.jar) and start by double-click or open a terminal and navigate to the folder with the downloaded file and type: `java -jar reqT.jar`
 
 ![reqT Main Window](img/screen1.png)