Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

should we re-think the approach to multiple platforms (was: 'Unix' misused throughout the material) #798

Open
loz-hurst opened this issue Jun 12, 2018 · 13 comments

Comments

@loz-hurst
Copy link
Contributor

@loz-hurst loz-hurst commented Jun 12, 2018

In a way this is related to #779.

Bourne Again SHell (BASH) is the shell used for this course, which is entitled "The Unix Shell". This seems fine to me as sh, which BASH derives from was called "Unix Shell".

However, the description of BASH as "The Unix Shell" has led to the conflation of the shell (program) and the operating system, which non-Unix OSs frequently described as Unix (esp. with regard to Linux, and there are legal reasons for not describing or implying Linux is, or derived from, a Unix) and the reference to Unix as the OS throughout the material when, most of the time, it means Unix-like.

There are also options for identifying and downloading a Unix Shell program, a Linux/UNIX emulator, or a program to access a UNIX server.

Directory names in a path are separated with / on Unix, but \ on Windows.

On Unix systems (such as Linux and Mac OS X)

There are numerous, and increasing, places scattered throughout the material where the differences between Unix (e.g. Mac OSX/BSD), Linux and Windows are noted as well as many gitlab issues related to the same. I wonder if it would be better to simply note that there are differences (without going into too much detail) somewhere and then audit the rest of the material to remove all the "it's slightly different on platform x from what is here" notes? (Perhaps replacing examples that are very different with ones that are the same - e.g., I think the '-F' flag was, looking at the number of issues related to just that, a poor choice to introduce flags to ls in lesson 1 (see #590 #644 for example) and '-l', which is works on all 3 platforms and is not the default alias for 'ls' on any, would have been a better but 'less clever looking' introduction for the novice.

@loz-hurst
Copy link
Contributor Author

@loz-hurst loz-hurst commented Jun 12, 2018

I think I'd like to start a discussion along the lines of "should we re-think the approach to multiple platforms" and look at if we can replace existing examples etc. with ones that work on all 3 major platforms without any major changes (e.g. just using '\' instead of '/' on Windows.

This would require a through going through of all the existing material to achieve, but should result in less GitHub issues, less confusing, simpler and easier to maintain material.

What do people think?

@loz-hurst loz-hurst changed the title 'Unix' misused throughout the material should we re-think the approach to multiple platforms (was: 'Unix' misused throughout the material) Jun 12, 2018
@loz-hurst
Copy link
Contributor Author

@loz-hurst loz-hurst commented Jun 12, 2018

Can someone label this issue 'discussion' - I don't seem to have rights to do it?

@gcapes
Copy link
Contributor

@gcapes gcapes commented Jun 12, 2018

Thanks for raising this issue.

For the purposes of a novice learning to use a tool (or indeed as an experienced user using a tool), I think any details about the differences and similarities between the terms UNIX/Unix/Linux/Unix-like are irrelevant. This isn't a history lesson after all! That's not to say that we shouldn't use the terms correctly in the material: I think we should.

I would be in favour of adding to the ls -F introduction -- currently the lesson just shows the output without explaining the meaning of the flag. Explaining that is classifies would be a good addition, per #644 (comment)

I'm not in favour of replacing the example with ls -l because this introduces the concept of permissions which are not covered in the lesson.

Making the lesson as platform-agnostic as possible is a worthy aim.

@loz-hurst
Copy link
Contributor Author

@loz-hurst loz-hurst commented Jun 12, 2018

Hi @gcapes this is my point, terminology is being confusingly (and incorrectly) used and notes about the differences are creeping in all over the lessons.

Regards the intricacies of the UNIX/Unix/Linux/*nix/Unix-like, I agree completely. I think the solution is to avoid using those terms unnecessarily, particularly when they can be replaced with a reference to the Unix Shell (which is, after all, what the course is about). For example "a program to access a UNIX server" is inaccurate in several ways and would be far better phrased as "a program to access a Unix Shell on a server". The nature of the server is entirely irreverential - a BASH environment on a Windows server accessed via RDP would be entirely viable for this course! I'll stick in a pull request for this.

ls -F is a good example because, according to one of the tickets I referenced, it does something completely different (colourises the output) in the Git for Windows emulation environment, which this course tells users to use as the preferred Windows option, to every other platform (where it categorises the files with a suffix). It is not a platform agnostic option and, therefore, either the content needs to updated to tell those using Windows the course notes are wrong on their platform (which I do not think is a good idea) or an option that is the same on all 3 needs to be used.

Edit:
This topic, "fixing" inaccuracies/inconsistencies by introducing platform specific notes, keeps getting discussed again and again. My hope with this issue to have the general discussion to try and understand the coherent approach (if there is one) to the issue as the content of the lessons and contributor opinions seem inconsistent at the moment (there's places with platform-specific notes and places where it's wrong on one or more platform but not corrected or addressed at all).

If we can agree an approach then this issue to be used to go through the material to implement it with what we have, and be referenced as the definitive discussion when it comes up again (as it inevitably will) in relation to a specific instance of platform-specific behaviour. The ls -F, as mentioned above, violates the "What Not to Contribute" notes in CONTRIBUTING.md as it does something entirely difference on Windows. It has not been the only example of this, although most have now been fixed:

Our workshops typically contain a mixture of Windows, Mac OS X, and Linux users; in order to be usable, our lessons must run equally well on all three.

I.e. I don't want to get bogged down in discussing specific instances, I'd like to have a discussion and reach a conclusion that the problems are going to be addressed and the general principals are going to be abided by in relation to this issue.

@gcapes
Copy link
Contributor

@gcapes gcapes commented Jun 12, 2018

I'll repeat here my correction (#590 (comment)) to the comment below :

ls -F is a good example because, according to one of the tickets I referenced, it does something completely different (colourises the output) in the Git for Windows emulation environment, which this course tells users to use as the preferred Windows option, to every other platform (where it categorises the files with a suffix).

This isn't the case for me testing just now with Git Bash. ls actually seems to be aliased to something like ls -F --colour=auto i.e. the default output is coloured and categorised, so ls and ls -F give the same output. If I run \ls, then I get a non-coloured, non-categorised output.


While it's a good aim to avoid examples which are very different on a particular OS, sometimes it won't be possible, and I think we have to accept that. The lesson is teaching the Unix Shell, and you're never giong to get that on Windows.

So the question remains: is it a problem having notes to explain what to expect on your particular OS if it's different to the lesson material? My thoughts (looking forward to hearing from others on this too):

  • Yes - it's clutter, which disrupts the flow of the material.
  • No - this information will be important to each learner that it helps/reassures.

Can we address both by moving some of it into callout boxes?

@gdevenyi
Copy link
Contributor

@gdevenyi gdevenyi commented Feb 15, 2019

From the perspective of a first-time learner, I think any instance which things come up differently than the lesson material is going to be concerning/confusing. From that perspective, I think it's imperative to note all outputs are somewhat regularized examples.

The question remains, how do we tell them that.

As I see it, two options:

  1. Callout boxes in each case where there could be a difference
  2. A largeish callout box to start explaining that small differences can arise and its hard to keep track of all the ways things could be different.

(1) is a lot of work, but (2) doesn't actually help learners to recognize when differences are meaningful, and when they're not. This is unfortunate.

@gcapes
Copy link
Contributor

@gcapes gcapes commented Feb 15, 2019

How about having a disclaimer near the beginning of the course to say that the examples throughout the course show the output from Bash on Linux.

We can explain that the Bash implementation is slightly different on a Mac, so there are some small differences to be expected in terms of the output and error messages. Git Bash is another implementation again, with its own set of differences. Git Bash is a good command-line interface to Git on Windows, but we're using it in the Unix Shell lesson as a 'try-before-you-buy' - you can learn how the commands and concepts work using it, but we're not really suggesting it as a set-up to use for your daily work (are we?).

I think we would still need some differences commented on in the notes like the way man doesn't work on Mac and help doesn't work on Git Bash (I think), but for enquiries about small differences we could encourage learners to use the red sticky note.

I appreciate that where output is different to the examples, it will be a source of potential confusion for learners. However to fully guard against that we would need three sets of output/error to be maintained for every example, which I don't think is workable or desirable.

TL;DR let's go for option 2.

@loz-hurst
Copy link
Contributor Author

@loz-hurst loz-hurst commented Feb 15, 2019

How about having a disclaimer near the beginning of the course to say that the examples throughout the course show the output from Bash on Linux.

My concern is that carpentries is intended to be taught to students using their own laptop computers. Of the 12 workshops we have delivered the number of students who have been using Linux is zero - so the materials are applicable to not a single one of over 300 deligates we have thought. We have to demonstrate what the output looks like to the Mac and Windows users every single time, taking valuable time out of delivering the materials and meaning the trainers have to hook up both types of machine to the projector to do the demonstration twice.

@gcapes
Copy link
Contributor

@gcapes gcapes commented Feb 15, 2019

Thanks @loz-hurst
Having re-read your original post I see you want option 3. which is for all the examples to work equally well on all platforms. That would be the ideal solution, but I don't know whether that is possible e.g. we would have to drop showing man or --help because only one of these works on Mac/Git Bash.

@gcapes
Copy link
Contributor

@gcapes gcapes commented Feb 15, 2019

Perhaps we can list (and link to the episode) for all the examples which give different output on Git Bash/Mac. Then we can see whether option 3 is achievable.

@LHurst-UoB
Copy link

@LHurst-UoB LHurst-UoB commented Apr 25, 2019

@gcapes

Having re-read your original post I see you want option 3.

What I want is to not teach a course that says "Also, capitalization matters: LS is different from ls." and 80% of the time someone in the classroom shouts "it's not on my computer". On Mac and Windows ls (being an external command on a case-insensitive filesystem) is not seen as different to LS (bash loops over the path and asks the filesystem for 'LS', for which a case-insensitive filesystem happily returns the program 'ls'. Why it's not different on these systems (combination external command, i.e. a program in $PATH, and case-insensitive filesystem) is a level of technical detail no-one at the level of this lesson should be exposed to but I have to explain why the materials are "wrong" (as the students see it) otherwise it undermines their confidence in the rest of the lessons.

My suggestion to insert the word "usually" in that particular sentence (making it technically accurate without introducing the complexity of explaining why it's not always the case) was rejected because "it's this way on Linux" (again, only true if you install Linux on a case-sensitive filesystem - it is possible for this not to be true on Linux as well) yet in over 300 people I've taught I've had not 1 single person running Linux on their computer turn up.

I'm utterly fed up of having to defend the rest of the materials to class-after-class of students who, once someone pipes up that LS and ls are the same on their system, seem to lose faith that the rest of the content is correct and entirely technically accurate and start trying to find mistakes in the rest of it - wasting precious time.

Surely I can't be the only person teaching this at a post-graduate level who's encountering the, rightfully, inquisitive minds of researchers who point out when the materials include an example that is demonstrably not consistent with the text for what I expect is the majority (I expect most Linux users would be unlikely to need to do the shell novice course, which is why I never see any on it) on SWC courses?

@gcapes
Copy link
Contributor

@gcapes gcapes commented May 17, 2019

Ok, I'm making a start on the list of examples where the output depends on your OS:

gcapes added a commit to gcapes/shell-novice that referenced this issue May 17, 2019
Fix swcarpentry#846.

- Explain ls -F more completely
- Explain REPL and commands in episode 1
- Move options and arguments explanation to episode 2
- Show example where captialisation matters, regardless of OS (see swcarpentry#798)
@loz-hurst
Copy link
Contributor Author

@loz-hurst loz-hurst commented Jun 7, 2019

@gcapes That's brilliant, thank you.

I've have a look through the issues you linked to and the proposed solutions to those would fix (I think) all of the instances I'm aware of.

My opinion is that we have about reached a conclusion with this issue: there will always be a few places we cannot avoid it (e.g. location of home directories and the lack of man and/or --help on some implementations) but I think we are agreed (which was the point of raising this issue - to try and see if we had a consensus and create a touchstone for it) that, as a community, should endeavour to minimise opportunities for confusion (which, in practice, means judiciously choosing examples that minimise clashes between platforms and being careful with how we present things when there are differences).

I agree that including multiple examples (to illustrate platform differences) would be counter-productive for novice learners and no better than "if you're running Windows this, if you're running Linux that and if your on a Mac the other" (yes, I know other platforms are available before anyone shouts!) which none of us think is a good idea.

@colinmorris referred to this as a "behemoth of an issue" in one of the linked issues - he's spot on with that but I, personally, am of the opinion we should hide from the behemoth issues that can seem too big to tackle - otherwise they perpetually lurk in the shadows and never get properly addressed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants