Update -h and man page as per jamuluswebsite/pull/714 (#2448)

gilgongo · web-flow · commit 56092960981a · 2022-03-24T17:13:28.000Z
diff --git a/distributions/Jamulus.1 b/distributions/Jamulus.1
@@ -60,82 +60,99 @@ is also possible.
 .Pp
 One participant starts
 .Nm
-in server mode, ideally on a dedicated server (virtual) machine;
-all participants start the (graphical) client which transmits audio
-to the server, receiving back a mixed stream.
+in Server mode, ideally on a dedicated server (virtual) machine;
+all participants start the (graphical) Client which transmits audio
+to the Server, receiving back a mixed stream.
 Use of a metronome is recommended.
 Clients should be connected using ethernet, not wireless, and use
 proper headphone and microphone connections, not Bluetooth.
-The server should run on a low-latency system, ideally not a VM.
+The Server should run on a low-latency system, ideally not a VM.
 .Pp
 Running
 .Nm
-without any extra options launches the full graphical client.
+without any extra options launches the full graphical Client.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl 6 | Fl \-enableipv6
 enable IPv6 support
 .It Fl c | Fl \-connect Ar address
-.Pq client mode only
-connect to the given server
+.Pq Client mode only
+connect to the given Server
 .Ar address
 .Pq Ar hostname Ns Op Ar :port
 at startup
 .It Fl d | Fl \-discononquit
-.Pq server mode only
-disconnect all clients on quit
+.Pq Server mode only
+disconnect all Clients on quit
 .It Fl e | Fl \-directoryserver Ar hostname
-.Pq server mode only
-make the server public and set its genre by setting the address
-of the directory server (formerly central server) to use to
+.Pq Server mode only
+Register the Server with the given Directory by setting the Directory Server Address to use to
 .Ar hostname ;
 see also
 .Fl o ;
-to be a directory server, use
+to be a Directory Server, use
 .Dq Li localhost
 .It Fl F | Fl \-fastupdate
-.Pq server mode only
-use 64 samples frame size mode, which reduces latency if clients connect with
+.Pq Server mode only
+use 64 samples frame size mode, which reduces latency if Clients connect with
 .Dq enable small network buffers
 turned on; requires a faster CPU to avoid dropouts and uses more bandwidth to
-connected clients
+connected Clients
+.It Fl \-jsonrpcsecretfile Ar file
+(Server mode only)
+Set the path to a text
+.Ar file
+containing an authentication string for obtaining access to the JSON-RPC API.
+This option is required when
+.Fl \-jsonrpcport
+is used.
+.It Fl \-jsonrpcport Ar port
+(Server mode only)
+Enables JSON-RPC API server to control the application, set the TCP
+.Ar port
+number.
+This API is
+.Em experimental
+and may change.
+It is only accessible from localhost.
+Please refer to the JSON-RPC API Documentation.
 .It Fl f | Fl \-listfilter Ar filter
-.Pq directory server mode only
-whitelist which servers are allowed to register on the server list;
+.Pq Directory mode only
+whitelist which Servers are allowed to register on the server list;
 .Ar filter
 must consist of semicolon-separated IP addresses
 .It Fl h | Fl \&? | Fl \-help
 display a short help text and exit immediately
 .It Fl i | Fl \-inifile Ar file
-.Pq client and non-headless server mode only
+.Pq Client and non-headless Server mode only
 override default initialisation file with
 .Ar file
 .It Fl j | Fl \-nojackconnect
-.Pq client mode only
+.Pq Client mode only
 do not automatically connect to JACK
 .It Fl L | Fl \-licence
-.Pq server mode only
-require clients to accept the agreement shown in the welcome message
+.Pq Server mode only
+require Clients to accept the agreement shown in the welcome message
 .Pq use Fl w No to set the text
 before they are allowed joining
 .It Fl l | Fl \-log Ar file
-.Pq server mode only
+.Pq Server mode only
 enable logging to
 .Ar file
 .It Fl M | Fl \-mutestream
-.Pq client mode only
+.Pq Client mode only
 start in muted state
 .It Fl m | Fl \-htmlstatus Ar file
-.Pq server mode only
-write server status and list of connected clients, in HTML format, to
+.Pq Server mode only
+write Server status and list of connected Clients, in HTML format, to
 .Ar file
 periodically
 .It Fl n | Fl \-nogui
 disable the GUI
 .It Fl o | Fl \-serverinfo Ar info
-.Pq public servers only
-set server location details, formatted as
+.Pq Registered Servers only
+set Server location details, formatted as
 .Sm off
 .Xo
 .Ar name Li \&;
@@ -151,7 +168,7 @@ see
 .Pa https://doc.qt.io/qt\-5/qlocale.html#Country\-enum
 for a list
 .It Fl P | Fl \-delaypan
-.Pq server mode only
+.Pq Server mode only
 start with delay panning enabled
 .It Fl p | Fl \-port Ar number
 set the local UDP port to use to
@@ -163,45 +180,45 @@ set QoS
 .Pq iptos byte
 to use
 .Pq default: 128
-.It Fl R | Fl \-recording Ar directory
-.Pq server mode only
+.It Fl R | Fl \-recording Ar Directory
+.Pq Server mode only
 enable recording
 .Pq but see Fl \-norecord
 storing tracks in
-.Ar directory
+.Ar Directory
 .It Fl s | Fl \-server
-start in server mode
+start in Server mode
 .It Fl T | Fl \-multithreading
-.Pq server mode only
+.Pq Server mode only
 use multithreading to make better use of multi-core CPUs and
-support more clients
+support more Clients
 .It Fl t | Fl \-notranslation
 disable translations, use built-in English strings
 .It Fl u | Fl \-numchannels
-.Pq server mode only
+.Pq Server mode only
 set maximum number of channels
 .Pq and , therefore , users ;
 default is 10, maximum is 150
 .It Fl v | Fl \-version
 display version information and exit immediately
 .It Fl w | Fl \-welcomemessage Ar message
-.Pq server mode only
+.Pq Server mode only
 show
 .Ar message
 .Pq may contain HTML and inline CSS
 to users on connect
 .It Fl z | Fl \-startminimized
-.Pq server mode only
+.Pq Server mode only
 start with minimised window
 .It Fl \-centralserver Ar hostname
-.Pq server mode only
+.Pq Server mode only
 deprecated alias for
 .Fl \-directoryserver
 .It Fl \-clientname Ar name
-.Pq client mode only
+.Pq Client mode only
 set window title and JACK client name
 .It Fl \-ctrlmidich Ar MIDISetup
-.Pq client mode only
+.Pq Client mode only
 set MIDI controller channel to listen on, control number offset and
 consecutive CC numbers (channels); format:
 .Sm off
@@ -227,48 +244,47 @@ left to right.
 does not provide feedback as to the current state of the Solo and Mute
 buttons so the controller must track and signal their state locally.
 .It Fl \-directoryfile Ar file
-.Pq directory server mode only
-enable server list persistence, storing to and loading from
-.Ar file
+.Pq Directory mode only
+remember registered Servers even if the Directory is restarted
 .It Fl \-mutemyown
-.Pq headless client only
+.Pq headless Client only
 mute my channel in my personal mix
 .It Fl \-norecord
-.Pq server mode only
+.Pq Server mode only
 do not automatically start recording even if configured with
 .Fl R
 .It Fl \-serverbindip Ar ip
-.Pq server mode only
+.Pq Server mode only
 configure Legacy IP address to bind to
 .It Fl \-serverpublicip Ar ip
-.Pq server mode only
-configure public Legacy IP address when both the directory server
-and the actual server are situated behind the same NAT, so that
-clients can connect
+.Pq Server mode only
+configure public legacy IP address when both the Directory Server
+and the actual Server are situated behind the same NAT, so that
+Clients can connect
 .It Fl \-showallservers
-.Pq client mode only
-show all registered servers in the serverlist regardless whether a ping
-to the server is possible or not
+.Pq Client mode only
+show all registered Servers in the serverlist regardless whether a ping
+to the Server is possible or not
 .Pq debugging command
 .It Fl \-showanalyzerconsole
-.Pq client mode only
+.Pq Client mode only
 show analyser console to debug network buffer properties
 .Pq debugging command
 .El
 .Pp
 Note that the debugging commands are not intended for general use.
 .Pp
 .Nm Jamulus
-knows four modes of operation: client mode and three kinds of server
-.Pq private , public , directory .
-A private server is unlisted, clients can only connect if given
+knows four modes of operation: Client mode and three kinds of Server
+.Pq Unregistered, Registered, Directory.
+A Unregistered Server is unlisted, Clients can only connect if given
 the address (IP address and port).
-A public server will contact a directory server (whose address must be
-given at server startup) and show up in that server's list; clients
-can retrieve a list of public servers from the directory server.
-Several public directory servers are operated by the Jamulus project;
-there is a directory server for each genre, which is how public Jamulus
-servers are categorised into genres.
+A Registered Server will contact a Directory (whose address must be
+given at Server startup) and show up in that Server's list; Clients
+can retrieve a list of Registered Servers from the Directory Server.
+Several Registered Directories are operated by the Jamulus project;
+there is a Directory for each genre, which is how Registered Jamulus
+Servers are categorised into genres.
 .Sh SEE ALSO
 .Xr qjackctl 1
 .Bl -tag -width Ds
@@ -277,15 +293,19 @@ online handbook
 .It Pa https://jamulus.io/wiki/FAQ
 frequently asked questions
 .It Pa https://jamulus.io/wiki/Running\-a\-Server
-documentation on server configuration and types
-.It Pa https://jamulus.io/wiki/Server\-Linux#running\-in\-public\-mode
-current list of directory servers operated by the Jamulus project,
+documentation on Server configuration and types
+.It Pa https://jamulus.io/wiki/Server\-Linux#running\-in\-registered\-mode
+current list of Directory Servers operated by the Jamulus project,
 controlling the
 .Dq genre
 .It Pa https://jamulus.io/wiki/Tips\-Tricks\-More
 verbose
 .Fl \-ctrlmidich
 documentation and other more or less useful information
+.It Pa https://github.com/jamulussoftware/jamulus/blob/master/docs/JSON\-RPC.md
+JSON-RPC API Documentation (see
+.Fl \-jsonrpcport
+above)
 .El
 .Sh AUTHORS
 .An -nosplit
diff --git a/src/main.cpp b/src/main.cpp
@@ -1014,7 +1014,7 @@ QString UsageArguments ( char** argv )
            "\n"
            "Common options:\n"
            "  -i, --inifile         initialization file name\n"
-           "                        (not supported for headless server mode)\n"
+           "                        (not supported for headless Server mode)\n"
            "  -n, --nogui           disable GUI (\"headless\")\n"
            "  -p, --port            set the local port number\n"
            "      --jsonrpcport     enable JSON-RPC server, set TCP port number\n"
@@ -1029,39 +1029,39 @@ QString UsageArguments ( char** argv )
            "  -6, --enableipv6      enable IPv6 addressing (IPv4 is always enabled)\n"
            "\n"
            "Server only:\n"
-           "  -d, --discononquit    disconnect all clients on quit\n"
-           "  -e, --directoryserver address of the directory server with which to register\n"
-           "                        (or 'localhost' to host a server list on this server)\n"
-           "      --directoryfile   enable server list persistence, set file name\n"
-           "  -f, --listfilter      server list whitelist filter.  Format:\n"
+           "  -d, --discononquit    disconnect all Clients on quit\n"
+           "  -e, --directoryserver address of the directory Server with which to register\n"
+           "                        (or 'localhost' to host a server list on this Server)\n"
+           "      --directoryfile   Remember registered Servers even if the Directory is restarted. Directory Servers only.\n"
+           "  -f, --listfilter      Server list whitelist filter.  Format:\n"
            "                        [IP address 1];[IP address 2];[IP address 3]; ...\n"
            "  -F, --fastupdate      use 64 samples frame size mode\n"
            "  -l, --log             enable logging, set file name\n"
            "  -L, --licence         show an agreement window before users can connect\n"
            "  -m, --htmlstatus      enable HTML status file, set file name\n"
-           "  -o, --serverinfo      registration info for this server.  Format:\n"
+           "  -o, --serverinfo      registration info for this Server.  Format:\n"
            "                        [name];[city];[country as QLocale ID]\n"
-           "      --serverpublicip  public IP address for this server.  Needed when\n"
+           "      --serverpublicip  public IP address for this Server.  Needed when\n"
            "                        registering with a server list hosted\n"
            "                        behind the same NAT\n"
            "  -P, --delaypan        start with delay panning enabled\n"
            "  -R, --recording       sets directory to contain recorded jams\n"
            "      --norecord        disables recording (when enabled by default by -R)\n"
-           "  -s, --server          start server\n"
-           "      --serverbindip    IP address the server will bind to (rather than all)\n"
+           "  -s, --server          start Server\n"
+           "      --serverbindip    IP address the Server will bind to (rather than all)\n"
            "  -T, --multithreading  use multithreading to make better use of\n"
-           "                        multi-core CPUs and support more clients\n"
+           "                        multi-core CPUs and support more Clients\n"
            "  -u, --numchannels     maximum number of channels\n"
            "  -w, --welcomemessage  welcome message to display on connect\n"
-           "                        (string or filename)\n"
+           "                        (string or filename, HTML supported)\n"
            "  -z, --startminimized  start minimizied\n"
            "\n"
            "Client only:\n"
-           "  -c, --connect         connect to given server address on startup\n"
-           "  -j, --nojackconnect   disable auto Jack connections\n"
+           "  -c, --connect         connect to given Server address on startup\n"
+           "  -j, --nojackconnect   disable auto JACK connections\n"
            "  -M, --mutestream      starts the application in muted state\n"
            "      --mutemyown       mute me in my personal mix (headless only)\n"
-           "      --clientname      client name (window title and jack client name)\n"
+           "      --clientname      Client name (window title and JACK client name)\n"
            "      --ctrlmidich      MIDI controller channel to listen\n"
            "\n"
            "Example: %1 -s --inifile myinifile.ini\n"
