Update -h and man page as per jamuluswebsite/pull/714 #2448
Conversation
gilgongo
changed the title
|
The PR title says "-f"? |
gilgongo
changed the title
| 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. |
There was a problem hiding this comment.
Use of a metronome is recommended.
By whom?
| 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. |
There was a problem hiding this comment.
ideally not a VM.
So why say "(virtual)" on line 63?
distributions/Jamulus.1
Outdated
| @@ -29,7 +29,7 @@ | |||
| .Op Fl P | Fl \-delaypan | |||
| .Op Fl p | Fl \-port Ar number | |||
| .Op Fl Q | Fl \-qos Ar value | |||
| .Op Fl R | Fl \-recording Ar directory | |||
| .Op Fl R | Fl \-recording Ar Directory | |||
There was a problem hiding this comment.
How do these appear? Single dash for the short option, clearly a double dash (not a long dash) for the long options?
There was a problem hiding this comment.
I suppose this means I'm going to have to work out how to compile a man page locally... Sigh.
There was a problem hiding this comment.
No need, man will do it for you. Just do man distributions/Jamulus.1 to view it.
There was a problem hiding this comment.
Fl x renders as -x (Fl means flag). GNU --long-options must be Fl \-long\-option (manpages are a BSD thing, GNU uses texinfo instead, so there’s no provision for GNU long options in manpages).
@softins man -l distributions/Jamulus.1 (-l = local) might be needed.
There was a problem hiding this comment.
@softins
man -l distributions/Jamulus.1(-l= local) might be needed.
It wasn't needed on my Pi running Raspbian 11.
In fact looking at man man, I see that it automatically tries again with an implicit -l, if it can't match the supplied argument with an installed man page, such as when giving a pathname instead of a simple name and section.
| .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: |
There was a problem hiding this comment.
The options are all a bit mixed up here.
In the --help output, they're now "Common" first, then "Server only", followed by "Client only". It might be easier reading if the man page were the same, using separate headings for each section.
There was a problem hiding this comment.
Last we spoke about this man page business, we hoped we'd automate it all out of -h (dropping all the stuff about recommending metromes and whatnot in the process) so that we don't manually maintain things in three places. It's only really there to satisfy Debian. Also doesn't help that I don't understand the syntax.
There was a problem hiding this comment.
@pljones options in manpages are supposed to be alphabetically sorted, case-insensitive (uppercase -Y before lowercase -y but after lowercase -x). Doing it a different way is very much not helpful.
@gilgongo manpages are supposed to be much more than just an option summary (you can get that from --help). It should also precisely explain how to use, concepts necessary, etc.
There was a problem hiding this comment.
@pljones options in manpages are supposed to be alphabetically sorted, case-insensitive (uppercase
-Ybefore lowercase-ybut after lowercase-x). Doing it a different way is very much not helpful.
They are alphabetical. They're just in separate sections that aren't related.
| 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 |
There was a problem hiding this comment.
Why is the word "legacy" here at all?
There was a problem hiding this comment.
“Legacy IP” is the contemporary wording for IPv4 (IP is IPv6). This was introduced into networking terminology a small number of years ago.
There was a problem hiding this comment.
So that all us old timers feel old...
| 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 |
There was a problem hiding this comment.
the address (IP address and port).
Not necessarily "IP address" - the host name is perfectly acceptable, if available. Port number is only necessary when it's not the default value. This can be covered here. Or link to the website for further discussion of "Server Address".
| servers are categorised into genres. | ||
| A Registered 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 Registered Servers from the Directory Server. |
There was a problem hiding this comment.
Directory Server
And anywhere else.
There was a problem hiding this comment.
It is. He said he'd be able to help with formatting, but not content.
|
Yup, looks like the man page needs an overhaul. I am so glad I don't write in man page format any more. Despite it being essential. |
|
@mirabilos just tagging you here since you wrote the man page and might want to comment |
distributions/Jamulus.1
Outdated
| @@ -29,7 +29,7 @@ | |||
| .Op Fl P | Fl \-delaypan | |||
| .Op Fl p | Fl \-port Ar number | |||
| .Op Fl Q | Fl \-qos Ar value | |||
| .Op Fl R | Fl \-recording Ar directory | |||
| .Op Fl R | Fl \-recording Ar Directory | |||
There was a problem hiding this comment.
Fl x renders as -x (Fl means flag). GNU --long-options must be Fl \-long\-option (manpages are a BSD thing, GNU uses texinfo instead, so there’s no provision for GNU long options in manpages).
@softins man -l distributions/Jamulus.1 (-l = local) might be needed.
| 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 |
There was a problem hiding this comment.
Wrong. The point of the PR is to capitalise "Server", "Client" and other relevant terms where referring to a running instance of Jamulus.
| 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. |
There was a problem hiding this comment.
The "Server" here is the Jamulus Server instance, not the machine it's running on.
| .Pq server mode only | ||
| disconnect all clients on quit | ||
| .Pq Server mode only | ||
| disconnect all Clients on quit |
distributions/Jamulus.1
Outdated
| 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 | ||
| make the Server Registered and set its genre by setting the address |
| enable server list persistence, storing to and loading from | ||
| .Ar file | ||
| .Pq Directory Server mode only | ||
| remember registered Servers even if the Directory is restarted |
There was a problem hiding this comment.
lowercase (also most of the others above here)…
There was a problem hiding this comment.
You've completely missed the point.
| 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 |
There was a problem hiding this comment.
“Legacy IP” is the contemporary wording for IPv4 (IP is IPv6). This was introduced into networking terminology a small number of years ago.
| .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 |
There was a problem hiding this comment.
404 Not Found
Don’t break the hyperlink.
There was a problem hiding this comment.
It won't get released until the website is updated.
|
Peter L Jones dixit:
> @pljones options in manpages are supposed to be alphabetically
> @sorted, case-insensitive (uppercase `-Y` before lowercase `-y` but
> @after lowercase `-x`). Doing it a different way is very much **not**
> @helpful.
They are alphabetical. They're just in separate sections that aren't related.
Right, and that’s fine for --help but not for manpages,
especially as it hurts searchability.
bye,
//mirabilos
--
Wish I had pine to hand :-( I'll give lynx a try, thanks.
Michael Schmitz on nntp://news.gmane.org/gmane.linux.debian.ports.68k
a.k.a. {news.gmane.org/nntp}#news.gmane.linux.debian.ports.68k in pine
|
If you're searching, the ordering has no effect. "/string" will find "string" wherever it is. Contextualising the result, however, remains important - so having the section heads is important in the manual page. Manual pages should be useful, not follow some pointless rules. |
|
@gilgongo I think you should add JSON-RPC to the man page with this PR. |
If can work out the syntax. |
|
Jonathan dixit:
> @gilgongo I think you should add JSON-RPC to the man page with this PR.
If can work out the syntax.
Write the text and indicate to me what should be formatted how
(there’s logical formatting) and I’ll help.
http://www.mirbsd.org/man7/mdoc and especially
http://www.mirbsd.org/man7/mdoc.samples should also help.
bye,
//mirabilos
--
15:41⎜<Lo-lan-do:#fusionforge> Somebody write a testsuite for helloworld :-)
|
|
@gilgongo can this be merged soon? |
|
@ann0see once the JSON-RPC stuff gets added I think, I yes. I'll have another look at that. |
|
on second thoughts...
|
|
Jonathan dixit:
on second thoughts...
***@***.***
> Write the text and indicate to me what should be formatted how
<<< in the DESCRIPTION section >>>
.It Fl \-jsonrpcsecretfile Ar file
(server 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 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.
<<< in the SEE ALSO section >>>
.It Pa https://github.com/jamulussoftware/jamulus/blob/master/docs/JSON\-RPC.md
JSON-RPC API Documentation (see
.Fl \-jsonrpcport
above)
bye,
//mirabilos
--
(gnutls can also be used, but if you are compiling lynx for your own use,
there is no reason to consider using that package)
-- Thomas E. Dickey on the Lynx mailing list, about OpenSSL
|
Short description of changes
Align wording and vocab with jamulussoftware/jamuluswebsite#714
CHANGELOG: Documentation: Made man page and help output more consistent.
Status of this Pull Request
I think
-his OK, but the man page is a bit of a rat's nest so needs some review.Checklist