Necessity of using the `$` in the git (.bash) code blocks? about git-novice HOT 17 CLOSED

The $ sign represents the shell prompt and, as you say, is a standard notation when showing shell commands. We use it in all our lessons. I'd like to keep it only for that reason, just following some conventions that our learners will find later.

But it also has a fundamental role, at least in my opinion, which is marking the extent of a command. A line with a $ is a command the user enters, while a line without the $ is an output line. Other prompts mean other things, like > in a for loop. Without the prompt, it would be very hard to say, for example, if a long command is one line or more.

Also, learners are supposed to type the commands, not just copy-paste them :-)

from git-novice.

@lwjohnst86 thanks for your suggestion.

@iglpdc great explanation.

This was raised in the past: carpentries/workshop-template#118.

from git-novice.

I understand that it is used throughout the shell lessons (which I think should be changed), but that (in my opinion) is not a strong argument for its continued use. However, regarding the role as indicating that it is command, is that not what the green vs blue code blocks are for? Neither R nor Python nor SQLite lesson commands use this notation 1, 2, 3, so why is that only the shell lessons use that? Why is the shell special enough to warrant the $ while the others are not? Again, I understand the history behind the use of the prompt, but SWC's mission is teaching "non-computer scientists", who frankly probably care less about the history of the use of $ and probably care more for consistence. As I said, I've had learners confused about this (some typing it into the console) and I have also been confused by it.

from git-novice.

@r-gaia-cs Thanks for the link, I hadn't seen that before. Just entered the comment above as you entered yours.

from git-novice.

I think that mentally interpreting code is one of the key skills in computing, and my understanding is that this is part of the SWC concept of providing scientists with an set of software engineering practices to give them a good start into scientific computing. From this perspective, incidents where students type a $ verbatim from code examples are an opportunity to reiterate that there are a bunch of special characters and these will have their respective meanings to the shell (regardless of whether that was intended / expected or not).

Having to switch focus to the shell in a git lesson is a disruption, of course, so if this is a frequent occurrence, a solution may be to place some more emphasis on special characters in the shell lesson?

Regarding cutting & pasting, I agree that this is a practice that should be avoided. It bypasses opportunities to mentally "parse" code, which seems to be triggered more "naturally" by typing than by cutting and pasting. Additionally, cutting and pasting commands can be dangerous, see [1]. This may not be the strongest of reasons for retaining the $ prompt, but personally I like the thought that enabling students to form commands by themselves will protect them from this silly kind of hack.

[1] https://thejh.net/misc/website-terminal-copy-paste

from git-novice.

Neither R nor Python nor SQLite lesson commands use this notation 1, 2, 3, so why is that only the shell lessons use that? Why is the shell special enough to warrant the $ while the others are not?

Good point, but there are slight differences. Python (or SQL or R) code is more often entered in a file or the notebook, rather than typed directly into the Python command line, so you don't really have a prompt to feed. Python code is going to give you a syntax error if you enter a wrong command, but probably nothing else happens. Bash code is harder to read, so it's easier to make mistake in interpreting where the line ends, and because it's so close to your OS, mistakes can be catastrophic. I think the extra $ worths the potential troubles of not knowing where the command ends. Silly example making very different things as a one- or as a two-liner:

cp silly_file_with_nothing_on_it.txt important_file_without_backup_and_long_name.txt 
destination_dir_that_sadly_went_to_next_line/

from git-novice.

I agree with everyone here that copy and paste for learners isn't what we are after and I am not suggesting that they should. I also recognize that within the context of shell and/or multiple lines, having the $ is useful. However, a look at the Shell (or Git) lessons, apart from the Loop section in the Shell lessons, there are no multi-liner commands and as such that argument doesn't make sense in SWC's context. I can also see that use of the prompt in other online tutorials on the shell is inconsistent (without 1 and with 2 the prompt, with several showing the commands as seen in the terminal 3, 4 which I really like as it is explicit), so it seems like it is up to the team doing the tutorials.

However, do a search for Git tutorials, and most 5, 6, 7, 8 don't use any prompt (some 9 explicitly show the terminal, which again I like). So do we want to be consistent with what learners will see out in the Internet after they finish SWC? (tho the official Git documentation uses the prompt 10 so...)

I can see that many people here have strong feelings about this, and I won't push it further if the consensus is to use the prompt, but I personally think that in the context of the Git lessons, the $ is ugly, unnecessary, distracting, and .. jarring.. (can't think of a better word).

Thanks for listening/reading :)

from git-novice.

Yes, but Github uses the $, for example [1]. It would be nice to get the CSS setup they use to do that [2], because it shows the prompt as an image, so if you copy/paste only the command, and not the $, is copied. For example, see the html from [1]:

<pre class="command-line">
<span class="command">git commit -m "Normalize all the line endings"</span>
</pre>

That'd be truly awesome.

@r-gaia-cs is this doable?

[1] https://help.github.com/articles/dealing-with-line-endings/
[2] https://help.github.com/assets/stylesheets/application.css and search for "command"

from git-novice.

👍 @iglpdc I agree! That does look very cool.

from git-novice.

Can you take a look at 02-create.html from https://github.com/r-gaia-cs/swc-git-novice/tree/git-css-for-prompt and see if its OK? It use CSS for the prompt so the user can't copy it.

@iglpdc Can we leave this for after v5.3? Please.

from git-novice.

@r-gaia-cs, sure! I was just curious if it was feasible. We could do this more calmly.

from git-novice.

I'm uneasy about using CSS to generate a $ that's there to see but not there to copy and paste. A very large majority of SWC students won't have the background knowledge of CSS and web technologies to understand this technique, so their experience may well be that "the computer magically does what's right", and quite easily slip into a belief that there's something magical about the dollar character. Also, the benefit to students will be short lived in the sense that they will experience the "jarring" when they copy & paste commands from a site that contains the $ in verbatim.

Thinking along the lines of addressing the copy & paste issue by web tech hacks, would it make sense to trigger an alert box upon copying from bash content, reminding the user to read and edit the command before issuing it?

from git-novice.

I think the CSS prompt is a good compromise. Learners still see the prompt there, so all the issues regarding what is the command are solved. On the other hand, if they need to copy/paste, it works better than they expect. Most people wouldn't notice the magic, I think.

from git-novice.

@gvwilson, @gdevenyi and @ChristinaLK What do you think of using CSS for the shell prompt after v5.3?

from git-novice.

@rgaiacs is this in the new CSS? Or does it matter at all with the new lesson template?

from git-novice.

@rgaiacs Can we close this? Does it matter anymore?

from git-novice.

See also carpentries/workshop-template#118

from git-novice.