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 · 5 comments

Comments

Projects
None yet
2 participants
@loz-hurst
Contributor

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

This comment has been minimized.

Contributor

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 from 'Unix' misused throughout the material to should we re-think the approach to multiple platforms (was: 'Unix' misused throughout the material) Jun 12, 2018

@loz-hurst

This comment has been minimized.

Contributor

loz-hurst commented Jun 12, 2018

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

@gcapes

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment