docs: Update "Getting Started" 01 and 02 #4854
Conversation
01 - Add a section on key combinations 02 - Remove discussions of key combinations now addressed in 01 and provide suggestions for clearer wordings of phrases
There was a problem hiding this comment.
thank you! these documents often don't get enough attention, so i really appreciate these updates.
i have some specific requests below and a few general notes:
- since you have already edited "the Mac" to "Mac" when it appears, would you mind fully correcting that to "macOS"? that is the official name of Apple's 10.x desktop OS
- when you are making a PR to this repo, it's best to create a feature branch instead of committing directly to persistent branches (master, develop, and 3.* release branches). otherwise you will have problems synchronizing your fork with this upstream repo. this is covered in a page on our wiki
| :: | ||
|
|
||
| Alternatively you can also first select the code you wish to execute and then press Ctrl-Enter (Cmd-Return on the Mac). Try this now. | ||
| Alternatively you can also first select the code you wish to execute (by clicking and dragging over the text until it is highlighted) and then press Ctrl-Enter (or Cmd-Return if you're on a Mac). Try this now. |
There was a problem hiding this comment.
"(Cmd-Return on macOS)" is enough
| @@ -60,7 +60,7 @@ code:: | |||
|
|
|||
| The first line, 'Hello there, I'm SuperCollider!' would not have printed if we didn't have the explicit postln. | |||
|
|
|||
| In general when you are meant to execute several lines of code at the same time they will be surrounded by parentheses, as in the example below. You can have your cursor anywhere in this region (or on the line of the parentheses on the Mac), then double-click and press Ctrl-Enter or Shift-Enter (Cmd-Return or Shift-Return on the Mac) - this selects the whole region and executes it. Try it out on the example below. | |||
| In general, when you are meant to execute several lines of code at the same time they will be surrounded by parentheses, as in the example below. You can have your cursor anywhere in this region (or on the line of the parentheses on the Mac), then double-click and press Ctrl-Enter or Shift-Enter (Cmd-Return or Shift-Return on Mac) - this selects the whole region and executes it. Try it out on the example below. | |||
There was a problem hiding this comment.
you could make a similar correction in "of the parentheses on the Mac"
| @@ -96,45 +96,43 @@ line 3 char 10: | |||
|
|
|||
| Usually the problem actually occurs a little before that, so that's where you should look. In this case, it's the lack of a semi-colon at the end of the previous line. Note that each line of code ends normally with a semi-colon. This is how you separate lines of code in SC. Since we didn't have a semi-colon between the two lines we have gotten an error. | |||
|
|
|||
| Using semi-colons it's possible to have more than one line of code in the same line of text. This can be handy for execution. | |||
| Using semi-colons, it's possible to have more than one code statement on the same line of text. This can be handy if you don't want to have to select multiple lines to execute related code statements. | |||
There was a problem hiding this comment.
imo this section should actually just be deleted; multiple statements on a single line is bad style and we shouldn't encourage it in our primary tutorial
There was a problem hiding this comment.
haha, I agree, will do. I felt like my edit was a little contrived, but I was trying to think about it from the point of view of someone who genuinely believed it to be a benefit
|
|
||
| They communicate by a protocol called Open Sound Control (OSC), over either UDP or TCP, which are network protocols also used on the internet. Don't think from this that the two applications must run on different computers (they can, which can have definite performance advantages), or that they need to be connected to the internet (although it is possible to have clients and servers in different parts of the world communicating!!). Most of the time they will be running on the same machine, and the 'networking' aspect of things will be relatively transparent for you. | ||
| They communicate by a protocol called Open Sound Control (OSC), over either UDP (User Datagram Protocol) or TCP (Transmission Control Protocol), which are network protocols also used on the internet. However, just because these two applications use protocols used on the internet, it is not necessary for them to run on different computers (though they can and there can be performance advantages to doing so), or that they need to be connected to the internet (although it is possible to have clients and servers in different parts of the world communicating!!). Most of the time they will be running on the same computer, and the "networking" aspect of things will be relatively transparent for you. |
There was a problem hiding this comment.
would you mind giving this paragraph another look? it doesn't make grammatical sense to me, and gets a bit convoluted with the parenthetical asides. in my experience, technical documentation is easier to read when there are fewer parentheticals. opinions differ, of course. also to be clear the explanations of abbreviations such as "UDP (User Datagram Protocol)" are totally fine.
There was a problem hiding this comment.
Understood, and I think I agree with you on your point about parentheticals. I'm taking a crack at making it more comprehensible, but feel free to lmk if there's anything that could still be improved in the next revision. This is kind of a cool point and it would be nice to make it sound exciting and clear to veteran coders while not too complex and scary to someone not super familiar with programming
| ##and the server, which does the actual synthesis and calculation of audio. | ||
| :: | ||
| The sclang part is a sophisticated programming language with nice GUI features; and the server part is a mean, lean, efficient UNIX command line application (meaning it runs without any GUI representation). | ||
| The sclang part is a sophisticated programming language with nice features for building GUI's (Graphical User Interfaces); and the server part is a lean, mean, efficient UNIX command line application (meaning it runs without any GUI representation). |
|
|
||
| As well, sometimes the post window becomes full of stuff and hard to read. You can clear it at any time by pressing Cmd-shift-p (hold down the command key and the shift key, and then press p). | ||
| Other times, the post window becomes full of text and is hard to read. You can clear it at any time by pressing Cmd-Shift-P. |
There was a problem hiding this comment.
i think this first sentence made more sense without the addition of "is"
|
|
||
| For example: "Ctrl-Enter" is a key combination of the "Ctrl" key and the "Enter" key. It means: press and hold down the "ctrl" key and then while keeping the "ctrl" key held down, press the "Enter" key. Once both are pressed down at the same time, you can release both keys. | ||
|
|
||
| "ctrl" is a key found on most Windows and Linux computers. Mac computers have a "ctrl" key, but when more than one key combination is given for the same instruction, the one that starts with "Cmd" is intended for Mac users. "Cmd" is short for "command" and is the key with "⌘" on it. |
There was a problem hiding this comment.
in these two paragraphs please capitalize "Ctrl" consistently
|
|
||
| You can only communicate with the server using OSC messages over the network, but luckily the language app has lots of powerful objects which represent things on the server and allow you to control them easily and elegantly. Understanding how exactly that works is crucial to mastering SC, so we'll be talking about that in some depth. | ||
|
|
||
| But first let's have a little fun, and make some sound... | ||
| But first let's have a little fun, and make some sound! |
Done :)
ahh, I totally misread this part of that page
and took it to mean that I should commit directly to that base. I will certainly do that going forward! For this PR tho, I think it'd be nice to preserve the conversation history and just leave the branch as is (unless there's an easy way to re-point this PR at a new branch). If the concern is just ease of development flow for me, I believe I have the git-fu needed to get me through any unusual rebasing challenges until this PR is closed 🤞 . But, if there's some other org-level reason why it would be good to have a more proper topic branch, I'm certainly happy to do that and just link back to this one. Thanks for taking the time to review closely! |
|
|
||
| "Ctrl" is a key found on most Windows and Linux computers. Mac computers have a "Ctrl" key, but when more than one key combination is given for the same instruction, the one that starts with "Cmd" is intended for Mac users. "Cmd" is short for "command" and is the key with "⌘" on it. | ||
|
|
||
| For key combinations with 3 or more keys, press the last key while holding down all the keys before it. For example, "Cmd-Shift-P" means: press and hold down the "Cmd" and "Shift" keys first, then press the "P" key while still holding "Cmd" and "Shift". |
There was a problem hiding this comment.
Would it be clearer to explain key combinations the other way around?
Currently, it's written as "do the last thing after doing the first things" and is a little confusing
There was a problem hiding this comment.
ya, I think you're right. My intent was to provide a terse definition and follow up with an example, but I think you're right that it's actually less clear. Will update
|
|
||
| As well, sometimes the post window becomes full of stuff and hard to read. You can clear it at any time by pressing Cmd-shift-p (hold down the command key and the shift key, and then press p). | ||
| Other times, the post window becomes full of text and hard to read. You can clear it at any time by pressing Cmd-Shift-P. |
There was a problem hiding this comment.
Can this be changed to Ctrl-Shift-P for consistency?
There was a problem hiding this comment.
I think this one still needs changing? Looks like you have corrected it somewhere else that I had missed (thanks for that!)
There was a problem hiding this comment.
haha, sweet! Good distributed coverage on our part 😆
| @@ -96,45 +96,41 @@ line 3 char 10: | |||
|
|
|||
| Usually the problem actually occurs a little before that, so that's where you should look. In this case, it's the lack of a semi-colon at the end of the previous line. Note that each line of code ends normally with a semi-colon. This is how you separate lines of code in SC. Since we didn't have a semi-colon between the two lines we have gotten an error. | |||
|
|
|||
| Using semi-colons it's possible to have more than one line of code in the same line of text. This can be handy for execution. | |||
|
|
|||
There was a problem hiding this comment.
can you please remove the code block below this as well?
There was a problem hiding this comment.
oh ha! yes, thank you for catching that :)
yes, that's fine! |
|
not waiting for the appveyor build -- apveyor is a bit overloaded from all the activity today and this is just a documentation change so it's 100% safe. |
01 - Add a section on key combinations
02 - Remove discussions of key combinations now addressed in 01 and provide suggestions for clearer wordings of phrases
Purpose and Motivation
SuperCollider was actually the first programming language I ever tried to learn, back in late 2009! It's been many years since I used it and wanted to brush up. Going through the "Getting Started" guide and figured I'd fix any typos along the way. After a few typos I started getting more opinionated and figured making slightly more opinionated changes is probably more in the spirit of open source. With that being said, I'm happy to break this PR apart or remove any atomic changes that are deemed problematic or unnecessary :)
Types of changes
To-do list