rebuild documentation and version strings

docs/index.html

@@ -441,7 +441,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">Nils Hilbricht</span><br>
-<span id="revnumber">version 1.5.3</span>
+<span id="revnumber">version 1.6.0</span>
 </div>
 </div>
 <div id="content">
@@ -556,8 +556,8 @@ Documentation and tutorials for software-developers will be added at a later dat
 </div>
 <div id="footer">
 <div id="footer-text">
-Version 1.5.3<br>
-Last updated 2022-01-15 13:33:32 +0100
+Version 1.6.0<br>
+Last updated 2022-03-05 12:20:42 +0100
 </div>
 </div>
 </body>

docs/src/api/index.adoc

@@ -1,6 +1,9 @@
 ////
 This is "asciidoctor", not plain "asciidoc".
 https://asciidoctor.org/docs/user-manual/
+
+100 characters per line (soft limit).
+
 ////
 
 
@@ -12,8 +15,12 @@ A copy of the license has been provided in the file documentation/API/LICENSE.
 ////
 
 
+////
+The revnumber API 1.1.1 below is autogenerated. Please do not touch this line.
+////
+
 :authors: Jonathan Moore Liles, Nils Hilbricht
-:revnumber: API 1.1.1
+:revnumber: API 1.1.2
 :revremark: License CC-By-SA v2.5
 :iconfont-remote!:
 :!webfonts:
@@ -161,6 +168,23 @@ to. Some unique component may be required to prevent collisions.
 
 ==== Session Root and Session Directories
 
+Client programs MUST NOT handle the following themselves. This section is background-information.
+
+NSM follows the link:https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specifications]
+
+All existing and new sessions are directories below the session-root, which defaults to
+`$XDG_DATA_HOME/nsm/`, which usually results in `$HOME/.local/share/nsm/`.
+
+Each session directory contains a file `session.nsm` with one client per line `name:executable:UID\n`
+For example:
+```
+JACKPatch:jackpatch:nBEIQ
+jack_mixer:jack_mixer:nTXHV
+Carla-Rack:carla-rack:nFAOD
+```
+`nsmd` loads and saves this file, client names are their self-reported names.
+The file format is final and frozen. Additions or changes SHALL NOT be made.
+
 ===== Subdirectories / Hierarchical Structure
 
 Subdirectories MAY be made to organize sessions into meaningful structures, such as album/track or
@@ -177,6 +201,32 @@ Any session itself MUST be a "leaf" in this directory tree. A session MUST NOT c
 session subdirectories: any directory that contains a file `session.nsm` is the final
 element in the hierarchy.
 
+===== Lockfiles
+
+Because multiple `nsmd` can run at the same time we need to prevent accidental write-access to the
+same session by different nsm-daemons, and subsequently GUIs.
+
+Therefore each currently open session creates a lockfile under `$XDG_RUNTIME_DIR/nsm/` (usually
+`/run/user/XXXX/nsm/`) that tells `nsmd` to not open such a locked session. This directory gets
+cleaned by the operating system, preventing sessions to stay locked after e.g. a power failure.
+
+The lockfile is named after the simple session name combined with a numeric ID for the session
+root. It is possible that two `nsmd` opened two different session roots, both with the same simple
+session name, e.g. "my song". Lockfiles are able to distinguish between those and will not prevent
+access in this scenario. The numeric ID is a djb2 hash modulo (%) 65521 of the session root directory
+(see `src/file.cpp` function `simple_hash()`).
+
+
+The lockfile contains, on separate lines:
+
+* The absolute path to the session, including the root-dir, which could be overriden by `nsmd --session-root`, allowing two sessions of the same basic name in different roots.
+* the OSC URL of the server that runs this session, the same as `$NSM_URL`.
+
+Example:
+```
+/home/johann/.local/share/nsm/cantatas/easter1751
+osc.udp://myuser.localdomain:11287/
+
 
 == NSM OSC Protocol
 
@@ -751,8 +801,8 @@ PATCH version when you make backwards compatible bug fixes.
 |Non Session Manager at moment of fork          | 1.2 (June 2020)
 |Non Session Manager API    | 1.0 link:https://github.com/original-male/non/blob/master/session-manager/src/nsmd.C[NON nsmd.C]
 |Original API Document      | 1.0 link:http://non.tuxfamily.org/nsm/API.html[non.tuxfamily.org/nsm/API.html]
-|New Session Manager        | 1.5.0
-|New Session Manager API    | 1.1.1 link:https://github.com/jackaudio/new-session-manager/blob/master/src/nsmd.cpp[NEW nsmd.cpp]
+|New Session Manager        | 1.6.0
+|New Session Manager API    | 1.1.2 link:https://github.com/jackaudio/new-session-manager/blob/master/src/nsmd.cpp[NEW nsmd.cpp]
 |New API Document   | 1.5.0 link:#[Here]
 
 |===
@@ -851,3 +901,9 @@ patch-level from 1.1.0 to 1.1.1
 * 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.
+
+=== Changes in API Version 1.1.2
+
+* nsmd now follows the XDG Base Directory Specifications for it's session root and lock files. This
+if of no consequence to clients but required documentation nevertheless, which was described as
+"background information" in the new section.

docs/src/index.adoc

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

docs/src/jackpatch.1

@@ -1,7 +1,7 @@
-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.5.
-.TH JACKPATCH "1" "January 2022" "jackpatch Version 1.5.3" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH JACKPATCH "1" "March 2022" "jackpatch Version 1.6.0" "User Commands"
 .SH NAME
-jackpatch \- manual page for jackpatch Version 1.5.3
+jackpatch \- manual page for jackpatch Version 1.6.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.48.5.
-.TH NSM-LEGACY-GUI "1" "January 2022" "nsm-legacy-gui Version 1.5.3" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH NSM-LEGACY-GUI "1" "March 2022" "nsm-legacy-gui Version 1.6.0" "User Commands"
 .SH NAME
-nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.5.3
+nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.6.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.48.5.
-.TH NSM-LEGACY-GUI "1" "January 2022" "nsm-legacy-gui Version 1.5.3" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH NSM-LEGACY-GUI "1" "March 2022" "nsm-legacy-gui Version 1.6.0" "User Commands"
 .SH NAME
-nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.5.3
+nsm-legacy-gui \- manual page for nsm-legacy-gui Version 1.6.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.48.5.
-.TH NSM-PROXY-GUI "1" "January 2022" "nsm-proxy-gui Version 1.5.3" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH NSM-PROXY-GUI "1" "March 2022" "nsm-proxy-gui Version 1.6.0" "User Commands"
 .SH NAME
-nsm-proxy-gui \- manual page for nsm-proxy-gui Version 1.5.3
+nsm-proxy-gui \- manual page for nsm-proxy-gui Version 1.6.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.48.5.
-.TH NSM-PROXY "1" "January 2022" "nsm-proxy Version 1.5.3" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH NSM-PROXY "1" "March 2022" "nsm-proxy Version 1.6.0" "User Commands"
 .SH NAME
-nsm-proxy \- manual page for nsm-proxy Version 1.5.3
+nsm-proxy \- manual page for nsm-proxy Version 1.6.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.48.5.
-.TH NSMD "1" "January 2022" "nsmd Version 1.5.3" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH NSMD "1" "March 2022" "nsmd Version 1.6.0" "User Commands"
 .SH NAME
-nsmd \- manual page for nsmd Version 1.5.3
+nsmd \- manual page for nsmd Version 1.6.0
 .SH DESCRIPTION
 nsmd \- Daemon and server for the 'New Session Manager'
 .SS "Usage:"
@@ -21,7 +21,7 @@ Show version
 OSC port number [Default: provided by system].
 .TP
 \fB\-\-session\-root\fR path
-Base path for sessions [Default: \fI\,~/NSM\/\fP Sessions].
+Base path for sessions [Default: $XDG_DATA_HOME/nsm/].
 .TP
 \fB\-\-load\-session\fR name
 Load existing session [Example: "My Song"].