regenerate documentation

README.md

@@ -1,11 +1,5 @@
 # New Session Manager
 
-Quick Links:
-* API Specifications
-  * https://linuxaudio.github.io/new-session-manager/api/index.html
-* WIKI with supported clients and information how to build NSM-capability into your own program
-  * https://github.com/linuxaudio/new-session-manager/wiki
-
 ## Introduction
 
 New Session Manager (NSM) is a tool to assist music production by grouping standalone programs into sessions.
@@ -71,7 +65,7 @@ which was released under the GNU GENERAL PUBLIC LICENSE  Version 2, June 1991.
 All files, except nsm.h kept in this fork were GPL "version 2 of the License, or (at your
 option) any later version."
 
-`extras/nsm.h/nsm.h` is licensed under the ISC License.
+`nsm.h` is licensed under the ISC License.
 
 New-Session-Manager changed the license to GNU GENERAL PUBLIC LICENSE, Version 3, 29 June 2007.
 See file COPYING

docs/api/index.html

@@ -443,7 +443,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <h1>New Session Manager - API</h1>
 <div class="details">
 <span id="author" class="author">Jonathan Moore Liles, Nils Hilbricht</span><br>
-<span id="revnumber">version API 1.1.0</span>
+<span id="revnumber">version API 1.1.1</span>
 <br><span id="revremark">License CC-By-SA v2.5</span>
 </div>
 <div id="toc" class="toc">
@@ -465,6 +465,11 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <ul class="sectlevel3">
 <li><a href="#_internal_files">1.2.1. Internal Files</a></li>
 <li><a href="#_external_files">1.2.2. External Files</a></li>
+<li><a href="#_session_root_and_session_directories">1.2.3. Session Root and Session Directories</a>
+<ul class="sectlevel4">
+<li><a href="#_subdirectories_hierarchical_structure">1.2.3.1. Subdirectories / Hierarchical Structure</a></li>
+</ul>
+</li>
 </ul>
 </li>
 </ul>
@@ -519,6 +524,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <ul class="sectlevel2">
 <li><a href="#_guidelines">3.1. Guidelines</a></li>
 <li><a href="#_changes_in_api_version_1_1_0">3.2. Changes in API Version 1.1.0</a></li>
+<li><a href="#_changes_in_api_version_1_1_1">3.3. Changes in API Version 1.1.1</a></li>
 </ul>
 </li>
 </ul>
@@ -578,9 +584,15 @@ and are therefore out of scope for this document.</p>
 <div class="paragraph">
 <p>However, the same server-side API can also be implemented by other programs (such as Carla),
 although consistency and robustness will likely suffer if non-NSM compliant clients are allowed to
-participate in a session. There is no direct dependency for client implementations, as long as they
-can send and receive OSC. Some clients use <code>liblo</code> (the OSC library), which becomes a dependency if
-you choose to implement NSM-support with the provided header file <code>nsm.h</code>.</p>
+participate in a session.</p>
+</div>
+<div class="paragraph">
+<p>There is no direct dependency for client implementations, as long as they
+can send and receive OSC.
+Some clients use <code>liblo</code> (the OSC library), which becomes a dependency if you choose to implement
+NSM-support with the provided header file <code>nsm.h</code> (<code>extras/nsm.h/nsm.h</code> in the git repository).
+Some clients use the provided single-file python library <code>pynsm</code> (<code>extras/pynsm/nsmclient.py</code> in the git repository)
+which has no dependencies outside the Python3 standard library.</p>
 </div>
 <div class="paragraph">
 <p>The aim of this project is to thoroughly define the behavior required of clients. Often the
@@ -691,6 +703,30 @@ session. The symlinks thus created should, at the very least, be named after the
 to. Some unique component may be required to prevent collisions.</p>
 </div>
 </div>
+<div class="sect3">
+<h4 id="_session_root_and_session_directories">1.2.3. Session Root and Session Directories</h4>
+<div class="sect4">
+<h5 id="_subdirectories_hierarchical_structure">1.2.3.1. Subdirectories / Hierarchical Structure</h5>
+<div class="paragraph">
+<p>Subdirectories MAY be made to organize sessions into meaningful structures, such as album/track or
+composer/genre/piece. For example: <code>Johann Sebastian Bach/Kantaten/Wie schön leuchtet der Morgenstern</code>.
+Which results in the same directory structure on disk. Session names can contain any characters that
+are supported by the underlying file system, usually UTF-8.</p>
+</div>
+<div class="paragraph">
+<p>Subdirectories are created by either <code>nsmd</code> itself or by the users themselves, through their file
+manager or a GUI (while the session is not open).</p>
+</div>
+<div class="paragraph">
+<p>The project_name from <code>/nsm/server/new s:project_name</code> accepts the format <code>a/b/c/d</code>.</p>
+</div>
+<div class="paragraph">
+<p>Any session itself MUST be a "leaf" in this directory tree. A session MUST NOT contain further
+session subdirectories: any directory that contains a file <code>session.nsm</code> is the final
+element in the hierarchy.</p>
+</div>
+</div>
+</div>
 </div>
 </div>
 </div>
@@ -831,7 +867,7 @@ the user.</p>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">optional-gui</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">server responds to optional-gui messages. If this capability is not present then clients with optional-guis MUST always keep them visible</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">server responds to optional-gui messages. This capability is always present and MUST be supported by any server implementation.</p></td>
 </tr>
 </tbody>
 </table>
@@ -1589,15 +1625,15 @@ PATCH version when you make backwards compatible bug fixes.</code></pre>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">New Session Manager</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1.4.0</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">1.5.0</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">New Session Manager API</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1.1.0 <a href="https://github.com/linuxaudio/new-session-manager/blob/master/src/nsmd.cpp">NEW nsmd.cpp</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">1.1.1 <a href="https://github.com/linuxaudio/new-session-manager/blob/master/src/nsmd.cpp">NEW nsmd.cpp</a></p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">New API Document</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1.4.0 <a href="#">Here</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">1.5.0 <a href="#">Here</a></p></td>
 </tr>
 </tbody>
 </table>
@@ -1736,13 +1772,35 @@ non-session-manager git.</p>
 </ul>
 </div>
 </div>
+<div class="sect2">
+<h3 id="_changes_in_api_version_1_1_1">3.3. Changes in API Version 1.1.1</h3>
+<div class="ulist">
+<ul>
+<li>
+<p>Server-capability :optional-gui: is now mandatory for SERVER implementations. Reasoning:
+This is an  important core feature of NSM and thus will be treated as such by guaranteeing it to exist.
+After looking at all currently known clients and server-implementations it turns out that all servers
+support :optional-gui: and the vast majority of clients not only support it, but actually assume it
+and do <em>not</em> test for the server capability, as it was written in this document.
+There are now two choices: Adjust this document to the (good) reality or consider all clients broken.
+Summary: We consider this API document wrong and therefore fix it, thus increasing API version
+patch-level from 1.1.0 to 1.1.1</p>
+</li>
+<li>
+<p>Add API-section "Subdirectories / Hierarchical Structure" that explains the session directory.
+This behaviour was already the case for nsm-legacy-gui and nsmd 1.5.0 was patched to adhere to this
+behaviour more strictly as well, removing false session entries in 3rd party clients such as Agordejo.</p>
+</li>
+</ul>
+</div>
+</div>
 </div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
-Version API 1.1.0<br>
-Last updated 2020-12-21 10:37:40 +0100
+Version API 1.1.1<br>
+Last updated 2020-12-26 17:03:24 +0100
 </div>
 </div>
 </body>

docs/index.html

@@ -443,7 +443,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <h1>New Session Manager Documentation</h1>
 <div class="details">
 <span id="author" class="author">LinuxAudio.org</span><br>
-<span id="revnumber">version 1.4.0</span>
+<span id="revnumber">version 1.5.0</span>
 </div>
 </div>
 <div id="content">
@@ -557,8 +557,8 @@ Documentation and tutorials for software-developers will be added at a later dat
 </div>
 <div id="footer">
 <div id="footer-text">
-Version 1.4.0<br>
-Last updated 2020-12-21 10:37:40 +0100
+Version 1.5.0<br>
+Last updated 2020-12-26 17:03:24 +0100
 </div>
 </div>
 </body>

docs/src/index.adoc

@@ -14,7 +14,7 @@ A copy of the license has been provided in the file documentation/LICENSE.
 :Author: LinuxAudio.org
 :iconfont-remote!:
 :!webfonts:
-:revnumber: 1.4.0
+:revnumber: 1.5.0
 
 = New Session Manager Documentation
 

docs/src/jackpatch.1

@@ -1,7 +1,7 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.16.
-.TH JACKPATCH "1" "December 2020" "jackpatch Version 1.4.0" "User Commands"
+.TH JACKPATCH "1" "December 2020" "jackpatch Version 1.5.0" "User Commands"
 .SH NAME
-jackpatch \- manual page for jackpatch Version 1.4.0
+jackpatch \- manual page for jackpatch Version 1.5.0
 .SH DESCRIPTION
 jackpatch \- Remember the JACK Audio Connection Kit Graph in NSM
 .PP

docs/src/non-session-manager.1

@@ -1,7 +1,7 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.16.
-.TH NSM-LEGACY-GUI "1" "December 2020" "nsm-legacy-gui Version 1.4.0" "User Commands"
+.TH NSM-LEGACY-GUI "1" "December 2020" "nsm-legacy-gui Version 1.5.0" "User Commands"
 .SH NAME
-nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.4.0
+nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.5.0
 .SH DESCRIPTION
 nsm\-legacy\-gui \- FLTK GUI for the 'New Session Manager'
 .SS "Usage:"

docs/src/nsm-legacy-gui.1

@@ -1,7 +1,7 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.16.
-.TH NSM-LEGACY-GUI "1" "December 2020" "nsm-legacy-gui Version 1.4.0" "User Commands"
+.TH NSM-LEGACY-GUI "1" "December 2020" "nsm-legacy-gui Version 1.5.0" "User Commands"
 .SH NAME
-nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.4.0
+nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.5.0
 .SH DESCRIPTION
 nsm\-legacy\-gui \- FLTK GUI for the 'New Session Manager'
 .SS "Usage:"

docs/src/nsm-proxy-gui.1

@@ -1,7 +1,7 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.16.
-.TH NSM-PROXY-GUI "1" "December 2020" "nsm-proxy-gui Version 1.4.0" "User Commands"
+.TH NSM-PROXY-GUI "1" "December 2020" "nsm-proxy-gui Version 1.5.0" "User Commands"
 .SH NAME
-nsm-proxy-gui \- manual page for nsm-proxy-gui Version 1.4.0
+nsm-proxy-gui \- manual page for nsm-proxy-gui Version 1.5.0
 .SH DESCRIPTION
 nsm\-proxy\-gui \- GUI for nsm\-proxy, a wrapper for executables without direct NSM\-Support.
 .SS "Usage:"

docs/src/nsm-proxy.1

@@ -1,7 +1,7 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.16.
-.TH NSM-PROXY "1" "December 2020" "nsm-proxy Version 1.4.0" "User Commands"
+.TH NSM-PROXY "1" "December 2020" "nsm-proxy Version 1.5.0" "User Commands"
 .SH NAME
-nsm-proxy \- manual page for nsm-proxy Version 1.4.0
+nsm-proxy \- manual page for nsm-proxy Version 1.5.0
 .SH DESCRIPTION
 nsm\-proxy \- Wrapper for executables without direct NSM\-Support.
 .PP

docs/src/nsmd.1

@@ -1,7 +1,7 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.16.
-.TH NSMD "1" "December 2020" "nsmd Version 1.4.0" "User Commands"
+.TH NSMD "1" "December 2020" "nsmd Version 1.5.0" "User Commands"
 .SH NAME
-nsmd \- manual page for nsmd Version 1.4.0
+nsmd \- manual page for nsmd Version 1.5.0
 .SH DESCRIPTION
 nsmd \- Daemon and server for the 'New Session Manager'
 .SS "Usage:"
@@ -31,6 +31,9 @@ Connect to running legacy\-gui [Example: osc.udp://mycomputer.localdomain:38356/
 .TP
 \fB\-\-detach\fR
 Detach from console.
+.TP
+\fB\-\-quiet\fR
+Suppress messages except warnings and errors.
 .PP
 nsmd can be run headless with existing sessions. To create new ones it is recommended to use a GUI
 such as nsm\-legacy\-gui (included) or Agordejo (separate package)

meson.build

@@ -24,7 +24,7 @@
 project(
 'new-session-manager',
 'c', 'cpp',
-version : '1.4.0',
+version : '1.5.0',
 license : 'GPLv3',
 )