search

jamulussoftware / jamulus

Jamulus enables musicians to perform real-time jam sessions over the internet.
https://jamulus.io
Other
1k stars 224 forks source link

Manual.md needs to be updated #274

Closed corrados closed 4 years ago

corrados commented 4 years ago

The Jamulus client manual at https://github.com/corrados/jamulus/blob/master/src/res/homepage/manual.md needs updates:

Any volunteers?

gilgongo commented 4 years ago

I'm assuming the new features that need explanation as of 3.5.4 are:

  1. Panning
  2. Indicator that another client has muted me
  3. Genre-based central server

Is that right? If so, I'll see if I can add those, add the language fixes, and update all the screenshots.

EDIT: Ah, updating binary files is going mean I need to work out how to use git to do that. Until now I've just been using the GH web interface. Hm.

corrados commented 4 years ago

Yes, these are basically the new features which should be added. Thanks.

gilgongo commented 4 years ago

Couple of questions about the genre-based central servers:

  1. How does the "custom" genre work?

  2. Can you check that the note I've put here for -e is correct?

BTW I assume that if a server is configured without -e it is a private server. But what does "default" mean in this case for -e? Can I set it without a value?

WolfganP commented 4 years ago

Talking about documentation, I think one of the concepts I struggled more was the audio paths clients/server flow and the controls interaction (ie Mute, Solo on faders section and myself)

I was thinking in augmenting https://github.com/corrados/jamulus/wiki/Getting-Started with a diagram like https://github.com/corrados/jamulus/issues/148#issuecomment-629679659 (by @matzix) but is probably better to keep that page simple as it is and expand to a more technical/advanced one to explain with more details?

What do you guys think?

gilgongo commented 4 years ago

I did in fact play about with a conceptual diagram as part of the never-ending quest to clarify the meaning of "mute" and "mute myself".

mute

But I didn't think it would really help. It's so easy to confuse people even more with diagrams I think. The above is as far as I got before concluding it was futile, as you can probably see :-)

corrados commented 4 years ago

How does the "custom" genre work?

You specify a custom URL or IP address in the Settings dialog of the Central Server you want to use. So if you e.g. want to use a server list which is hosted at jamulus.example.com you set the Custom Central Server Address edit box to "jamulus.example.com" and in the Connect Dialog on the top left drop down list you select Custom.

Can you check that the note I've put here for -e is correct?

Looks ok to me.

gilgongo commented 4 years ago

Oh OK . So that's how the client selects a different central server. I expect some people might wonder what it means in the context of genres though, so I hope we can explain it clearly enough. Something like this?

"Your can set up your own list of servers (that is, a 'custom central server'). You need to tell other server operators to register their servers with your custom server, and then tell those server operators to tell their users to set their clients to your central server so that those clients can see their servers listed by your custom server."

:-)

Another question: What's the difference between "Default" and "All Genres"?

And talking of which, I assume that if a server is configured without -e it is a private server. But what does "default" mean in this case? Can I set -e without a value to have it use the default?

corrados commented 4 years ago

Something like this?

Your text is correct but really sounds a bit funny :-). Maybe a picture helps...

What's the difference between "Default" and "All Genres"?

That's caused by compatibility issues. Since we are now using genre based servers, a "north america" server seems not to fit in. Since the server operators which have registered to the two old servers did not have a genre in mind, I decided to use a name which includes all genres.

And talking of which, I assume that if a server is configured without -e it is a private server. But what does "default" mean in this case? Can I set -e without a value to have it use the default?

If you have a private server, you do not need any Default central server since you do not register anyway. So you are completely independent of any server list but the clients must connect to your server by using an IP address or DynDNS URL.

Matzix commented 4 years ago

a diagram like #148 (comment) (by @Matzix)

What are best practices to draw a diagram, such that it can be used in documentation and also be edited by others (graphic tools, file formats, ...)?

WolfganP commented 4 years ago

a diagram like #148 (comment) (by @Matzix)

What are best practices to draw a diagram, such that it can be used in documentation and also be edited by others (graphic tools, file formats, ...)?

No idea if there's any preferred diagram collaborative tool, but I prefer it be some (accessible, free, easy to use, ...) tool like LibreOffice Draw or some online solution like Draw.io

gilgongo commented 4 years ago

@Matzix I used some free diagramming thing. It was a bit fiddly though, so not sure if it's that good really. See this comment.

gilgongo commented 4 years ago

but really sounds a bit funny

Hehe - yes, I wasn't taking it very seriously, sorry :-)

The concept of the custom server is going to be hard to document without people getting confused I think. It will be easier if we can give some example use cases for it. The only one I know of is for something like a virtual music festival, so you can collect a bunch of participating servers and then advertise for clients to connect to that central server for the duration of that event. Are there others?

WolfganP commented 4 years ago

Thx @gilgongo I didn't find https://github.com/corrados/jamulus/issues/64 before, that will be a better place to collaborate on visual diagrams

ignotus666 commented 4 years ago

I've applied the corrections to the manual.md file, but as I said in the pull request, I'm not entirely confident about my technical knowledge to update it with the new features.

gilgongo commented 4 years ago

I'm having a look at updating manual.md to add the new features and screenshots. There are a number of tweaks that are needed I think.

corrados commented 4 years ago

OK, great. But please wait before you start until I have merged the pull request.

corrados commented 4 years ago

The only one I know of is for something like a virtual music festival, so you can collect a bunch of participating servers and then advertise for clients to connect to that central server for the duration of that event. Are there others?

You are talking about, e.g., the word jam event on Facebook, right? What I have seen was a list of servers specifically for choir sessions. I make sense not to put them in the official list to prevent other clients to enter a rehearsal.

corrados commented 4 years ago

BTW: I have just merged the pull request.

gilgongo commented 4 years ago

Sorry for delay on this - just trying to work out how to use git. I tried Git Desktop (on Win and Mac) and for some reason when I clone the repo it gives me an old version (eg manual.md has the server setup instructions in it). So I've abandoned that.

To put me out of my misery, what do I need to do on the command line?

git clone

git checkout -b issue274

[do some edits]

git commit -a -m 'Some comment here'

And then I can do the pull request in the web interface? Not sure.

BTW I thought I'd try shortening the text in manual.md a bit as well as adding descriptions of the new features and screen shots (if I can get them all - my server lists are very short so I might have to ask somebody else to take a couple).

ignotus666 commented 4 years ago

Are you forking corrados/jamulus? You need to do that first, which will create your own Jamulus repository in your git account, and then you clone that to your computer with git clone https://github.com/gilgongo/jamulus.git. Make your edits, upload them to the Jamulus fork in your repository, and then from there you make the pull request.

Edit: I see you do have your own fork. To get it up to date you can delete it and fork it again or do this: https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser

gilgongo commented 4 years ago

@ignotus666 OK cloning creates a fork, I see. So I need to delete the gilgongo/jamulus repo, then git clone https://github.com/gilgongo/jamulus.git, make the changes, and then what? git commit?

EDIT: Actually, once I've cloned my fork, I do a git checkout as above, yes?

ignotus666 commented 4 years ago

No; delete gilgongo/jamulus, come back to corrados/jamulus and fork it - this will create an updated fork of jamulus (gilgongo/jamulus). If you delete it and try to clone it with git clone https://github.com/gilgongo/jamulus.git it won't work because there'll be nothing to clone.

the git clone command will create a copy of the jamulus files on your PC. You can edit them there, and when ready, I'm not sure about the command, but what I do is just go to my repository (in your case gilgongo/jamulus), go to the directory where the edited files are, and click on "upload files". Just select your edited files and they'll be uploaded to your fork. Then, you click on "make a new pull request" (or something to that effect). Give your pull request a name and optionally a description and that's it.

gilgongo commented 4 years ago

Sorry, I meant git clone https://github.com/corrados/jamulus.git after I'd deleted gilgongo/jamulus

OK I didn't see the "upload files" button. I can use that for the screenshots then so I don't have to use git.

Thanks - I'll give that a go.

gilgongo commented 4 years ago

OK I've done that PR now.

corrados commented 4 years ago

Great, thank you. I just merged your changes.

ignotus666 commented 4 years ago

I suppose these changes now need to be reflected in the software itself and the translations. I can volunteer to do that and have a go at properly revising the text while I'm at it, but it might take some time because I'm pretty busy with work right now.

Ok, so I just found out how to update the .ts files without editing them one by one, using lupdate... I've been making things much harder for myself than they needed to be. Feeling pretty stupid.

gilgongo commented 4 years ago

I made quite a large number of minor changes in manual.md, so if the diffs are confusing, the main things are:

Replaced the first section of the old description of the Connection Window with a description of genre based servers.

Added "Mute Myself button" section.

In "Server audio mixer" section, added pan control description and updated Mute and Solo button descriptions.

Replaced old "Central Server" section with new "Custom central server address" description.

BTW there are some typos I'd like to fix, and I'd like to go around again on the screenshots at some point so I may do another PR in the next few days maybe.

ignotus666 commented 4 years ago

Ok, I'll wait for that to happen and will then reflect your changes in the source files where appropriate and carry out a more in-depth revision of the rest of the texts.

corrados commented 4 years ago

I fear all the "+ APP_NAME +" in the translation code will make problems now. Maybe these should be reduced. But this will cause a lot of effort for all the translations...

ignotus666 commented 4 years ago

What about getting rid of them altogether and just replacing them with "Jamulus"?

corrados commented 4 years ago

My preferred solution would be to exchange this by something more general. E.g., instead of "by using the Jamulus software, ..." one could write "by using this app, ...".

ignotus666 commented 4 years ago

Or "by using Jamulus ...".

corrados commented 4 years ago

No, this is not what I want. I do not want to have the name "Jamulus" in the help files. That is the reason I have chosen "this app" in my example.

ignotus666 commented 4 years ago

Ok, I understand. I've started working on a revision of the texts (very early stages still). When it's done it would be good for Volker and maybe others to have a look at it to suggest possible changes/corrections. Should I just do a PR or what would be the best way?

OTOH, I see obsolete segments can be removed with lupdate, but I think it might be better to leave them until after the translations are done, as translators can reuse large chunks of the obsolete translations.

corrados commented 4 years ago

Yes, you should leave the vanished translation texts.

I guess the translators will have a lot of work when you are done. I hope they are willing to spend that time.

Should I just do a PR or what would be the best way?

Yes, just do a PR.

corrados commented 4 years ago

Since my initial request of this Issue is already been worked on, I will close this Issue now. Of course, if we add new features to Jamulus, the manual has to be adapted again. But this is not the scope of this issue.