You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _extras/guide.md
+51-76Lines changed: 51 additions & 76 deletions
Original file line number
Diff line number
Diff line change
@@ -3,16 +3,13 @@ layout: page
3
3
title: "Instructor Notes"
4
4
---
5
5
6
-
____
7
-
# Tips and Tricks
6
+
## Tips and Tricks
8
7
9
-
____
10
-
## Making a handout
8
+
### Making a handout
11
9
12
10
Librarians like handouts. To make a handout for this lesson, adapt/print from [https://librarycarpentry.org/lc-shell/reference](https://librarycarpentry.org/lc-shell/reference).
13
11
14
-
______
15
-
## Differences between platforms
12
+
### Differences between platforms
16
13
17
14
Some of the commands used in this lesson behave differently depending on whether they are run on Git Bash for Windows, macOS X or Linux. Be prepared to manage these differences. Here are some examples from episode 5, "Counting and mining with the shell":
18
15
@@ -26,13 +23,11 @@ Some of the commands used in this lesson behave differently depending on whether
26
23
27
24
As noted below, you should avoid demonstrating any more options that only work on certain platforms.
28
25
29
-
_____
30
-
# General notes on shell
26
+
## General notes on shell
31
27
32
28
- Why do we learn to use the shell?
33
29
- Allows users to automate repetitive tasks
34
-
- And capture small data manipulation steps that are normally not recorded
35
-
to make research reproducible
30
+
- And capture small data manipulation steps that are normally not recorded to make research reproducible
36
31
- The Problem
37
32
- Running the same workflow on several samples can be unnecessarily labour intensive
38
33
- Manual manipulation of data files:
@@ -44,7 +39,7 @@ _____
44
39
- Built-in commands allow for easy data manipulation (e.g. `sort`, `grep`, etc.)
45
40
- Every step can be captured in the shell script and allow reproducibility and easy troubleshooting
46
41
47
-
## Overall
42
+
###Overall
48
43
49
44
Many people have questioned whether we should still teach the shell.
50
45
After all,
@@ -86,12 +81,10 @@ using high-performance computing infrastructure,
86
81
and running new specialist tools in many disciplines.
87
82
We do not teach HPC or domain-specific skills here
88
83
but lay the groundwork for further development of these skills.
89
-
In particular,
90
-
understanding the syntax of commands, flags, and help systems is useful for domain specific tools
84
+
In particular, understanding the syntax of commands, flags, and help systems is useful for domain specific tools
91
85
and understanding the file system (and how to navigate it) is useful for remote access.
92
86
93
-
Finally,
94
-
and perhaps most importantly,
87
+
Finally, and perhaps most importantly,
95
88
teaching people the shell lets us teach them
96
89
to think about programming in terms of function composition.
97
90
In the case of the shell,
@@ -103,48 +96,44 @@ as long as learners using Windows do not run into roadblocks such as:
103
96
104
97
- not being able to figure out where their home directory is
105
98
(particularly if they're using Cygwin);
106
-
- not being able to run a plain text editor;
107
-
and
99
+
- not being able to run a plain text editor; and
108
100
- the shell refusing to run scripts that include DOS line endings.
109
101
110
-
## Preparing to Teach
102
+
###Preparing to Teach
111
103
112
104
- Use the `data` directory for in-workshop exercises and live coding examples.
113
105
You can clone the shell-novice directory or use the `Download ZIP`
114
-
button on the right to get the entire [repository](https://github.com/swcarpentry/shell-novice). We also now provide
106
+
button on the right to get the entire [repository](https://github.com/librarycarpentry/lc-shell). We also now provide
115
107
a zip file of the `data` directory that can be downloaded on its own
116
108
from the repository by right-click + save or see the ["setup"]({{ page.root }}{% link setup.md %}) page on the lesson website for more details.
117
109
118
110
- Website: various practices have been used.
119
111
- Option 1: Can give links to learners before the lesson so they can follow along,
120
-
catch up,
121
-
and see exercises (particularly if you're following the lesson content without many changes).
112
+
catch up, and see exercises (particularly if you're following the lesson content without many changes).
122
113
- Option 2: Don't show the website to the learners during the lesson, as it can be distracting:
123
114
students may read instead of listen, and having another window open is an additional cognitive load.
124
115
- In any case, make sure to point to website as a post-workshop reference.
125
116
126
117
- Content:
127
-
Unless you have a truly generous amount of time (4+ hours),
118
+
-Unless you have a truly generous amount of time (4+ hours),
128
119
it is likely that you will not cover ALL the material in this lesson in a single half-day session.
129
120
Plan ahead on what you might skip, what you really want to emphasize, etc.
130
121
131
122
- Exercises:
132
-
Think in advance about how you might want to handle exercises during the lesson.
123
+
-Think in advance about how you might want to handle exercises during the lesson.
133
124
How are you assigning them (website, slide, handout)?
134
125
Do you want everyone to try it and then you show the solution?
135
126
Have a learner show the solution?
136
127
Have groups each do a different exercise and present their solutions?
137
128
138
-
-`reference.md` can be printed out and given to students as a reference, your choice.
139
-
140
129
- Other preparation:
141
-
Feel free to add your own examples or side comments,
130
+
-Feel free to add your own examples or side comments,
142
131
but know that it shouldn't be necessary:
143
132
the topics and commands can be taught as given on the lesson pages.
144
133
If you think there is a place where the lesson is lacking,
145
134
feel free to file an issue or submit a pull request.
146
135
147
-
## Teaching Notes
136
+
###Teaching Notes
148
137
149
138
- Super cool online resource!
150
139
<https://explainshell.com/> will dissect any shell command you type in
@@ -159,8 +148,7 @@ as long as learners using Windows do not run into roadblocks such as:
159
148
- Running a text editor from the command line can be
160
149
the biggest stumbling block during the entire lesson:
161
150
many will try to run the same editor as the instructor
162
-
or will not know how to navigate to the right directory
163
-
to save their file,
151
+
or will not know how to navigate to the right directory to save their file,
164
152
or will run a word processor rather than a plain text editor.
165
153
The quickest way past these problems is to have more knowledgeable learners
166
154
help those who need it.
@@ -179,19 +167,14 @@ as long as learners using Windows do not run into roadblocks such as:
179
167
180
168
- Building up a pipeline with four or five stages,
181
169
then putting it in a shell script for re-use
182
-
and calling that script inside a `for` loop,
183
-
is a great opportunity to show how
184
-
"seven plus or minus two"
185
-
connects to programming.
170
+
and calling that script inside a `for` loop, is a great opportunity to show how
171
+
"seven plus or minus two" connects to programming.
186
172
Once we have figured out how to do something moderately complicated,
187
173
we make it re-usable and give it a name
188
-
so that it only takes up one slot in working memory
189
-
rather than several.
174
+
so that it only takes up one slot in working memory rather than several.
190
175
It is also a good opportunity to talk about exploratory programming:
191
-
rather than designing a program up front,
192
-
we can do a few useful things
193
-
and then retroactively decide which are worth encapsulating
194
-
for future re-use.
176
+
rather than designing a program up front, we can do a few useful things
177
+
and then retroactively decide which are worth encapsulating for future re-use.
195
178
196
179
- If everything is going well, you can drive home the point that file
197
180
extensions are essentially there to help computers (and human
@@ -208,45 +191,18 @@ as long as learners using Windows do not run into roadblocks such as:
208
191
If learners already understand the basic material,
209
192
this can be covered instead using the online lessons as guidelines.
210
193
These limitations also have follow-on consequences:
211
-
212
-
- It's hard to discuss `#!` (shebang) without first discussing
194
+
- It's hard to discuss `#!` (shebang) without first discussing
213
195
permissions, which we don't do. `#!` is also [pretty
214
196
complicated][shebang], so even if we did discuss permissions, we
215
197
probably still wouldn't want to discuss `#!`.
216
198
217
-
- Installing Bash and a reasonable set of Unix commands on Windows
218
-
always involves some fiddling and frustration.
219
-
Please see the latest set of installation guidelines for advice,
220
-
and try it out yourself *before* teaching a class.
221
-
222
-
- On Windows machines
223
-
if `nano` hasn't been properly installed with the
224
-
[Software Carpentry Windows Installer][windows-installer]
225
-
it is possible to use `notepad` as an alternative. There will be a GUI
226
-
interface and line endings are treated differently, but otherwise, for
227
-
the purposes of this lesson, `notepad` and `nano` can be used almost interchangeably.
228
-
229
-
- On Windows, it appears that:
230
-
231
-
~~~
232
-
$ cd
233
-
$ cd Desktop
234
-
~~~
235
-
{: .bash}
236
-
237
-
will always put someone on their desktop.
238
-
Have them create the example directory for the shell exercises there
239
-
so that they can find it easily
240
-
and watch it evolve.
241
-
242
199
- Stay within POSIX-compliant commands, as all the teaching materials do.
243
200
Your particular shell may have extensions beyond POSIX that are not available
244
201
on other machines, especially the default OSX bash and Windows bash emulators.
245
202
For example, POSIX `ls` does not have an `--ignore=` or `-I` option, and POSIX
246
203
`head` takes `-n 10` or `-10`, but not the long form of `--lines=10`.
247
204
248
-
249
-
## Windows
205
+
### Windows
250
206
251
207
Installing Bash and a reasonable set of Unix commands on Windows
252
208
always involves some fiddling and frustration.
@@ -260,22 +216,41 @@ Options we have explored include:
260
216
4. having learners connect to a remote Unix machine (typically a VM in the cloud).
261
217
262
218
Cygwin was the preferred option until mid-2013,
263
-
but once we started teaching Git,
264
-
Git Bash proved to work better.
219
+
but once we started teaching Git, Git Bash proved to work better.
265
220
Desktop virtual machines and cloud-based VMs work well for technically sophisticated learners,
266
-
and can reduce installation and configuration at the start of the workshop,
267
-
but:
221
+
and can reduce installation and configuration at the start of the workshop, but:
268
222
269
223
1. they don't work well on underpowered machines,
270
224
2. they're confusing for novices (because simple things like copy and paste work differently),
271
225
3. learners leave the workshop without a working environment on their operating system of choice, and
272
226
4. learners may show up without having downloaded the VM or the wireless will go down (or become congested) during the lesson.
273
227
274
-
Whatever you use,
275
-
please *test it yourself* on a Windows machine *before* your workshop:
228
+
Whatever you use, please *test it yourself* on a Windows machine *before* your workshop:
276
229
things may always have changed behind your back since your last workshop.
277
-
And please also make use of our
278
-
[Software Carpentry Windows Installer][windows-installer].
230
+
And please also make use of our [Software Carpentry Windows Installer][windows-installer].
231
+
232
+
#### Windows Notes
233
+
234
+
- On Windows machines
235
+
if `nano` hasn't been properly installed with the
236
+
[Software Carpentry Windows Installer][windows-installer]
237
+
it is possible to use `notepad` as an alternative. There will be a GUI
238
+
interface and line endings are treated differently, but otherwise, for
239
+
the purposes of this lesson, `notepad` and `nano` can be used almost interchangeably.
240
+
241
+
- On Windows, it appears that:
242
+
243
+
~~~
244
+
$ cd
245
+
$ cd Desktop
246
+
~~~
247
+
{: .bash}
248
+
249
+
... will always put someone on their desktop.
250
+
Have them create the example directory for the shell exercises there
251
+
so that they can find it easily and watch it evolve.
0 commit comments