ShellTutorial/1-commands.sh at master · SmallSatGasTeam/ShellTutorial · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/bin/sh

. .lib/shell-compat-test.sh

_DURATION=20
_LSN_VERSION=1.0.0

# Put tutorial library files into $PATH if they are not already added
if [[ -d "$PWD/.lib" && ":$PATH:" != *":$PWD/.lib:"* ]]; then
	PATH=$PWD/.lib:$PATH
fi

source ansi-terminal-ctl.sh
source open.sh
source progress.sh

if [[ -n $_TUTR ]]; then
	source generic-error.sh
	source noop.sh
	source platform.sh
	source quiz.sh
	_Google() { echo ${_B}G${_R}o${_Y}o${_B}g${_G}l${_R}e${_z}; }
	_err() { (( $# == 0 )) && echo $(red _err) || echo $(red "$*"); }
fi

_man_not_found() {
	case $_PLAT in
		*MINGW*)
			cat <<-MNF
			The command $(cmd man) was not found.  It is required for this lesson.

			Read "$(bld Installing the Unix Manual)" in $(path README.md) to learn how to set this
			up. I will open this page for you now.

			If this error persists, contact $_EMAIL
			MNF
			_tutr_open 'https://github.com/SmallSatGasTeam/ShellTutorial#installing-the-unix-manual'
			;;
		*)
		cat <<-MNF
			The command $(cmd man) was not found.  It is required for this lesson.

			Contact $_EMAIL for help
			MNF
			;;
	esac
}

setup() {
	source screen-size.sh 80 30
	source platform.sh
	source assert-program-exists.sh
	_tutr_assert_program_exists man _man_not_found

	export _BASE="$PWD/lesson1"
	[[ -d "$_BASE" ]] && rm -rf "$_BASE"
	mkdir -p "$_BASE"

	export EFILE=elegant
	cat <<-TEXT > "$_BASE/$EFILE"
		elegant: adj.

		  [common; from mathematical usage] Combining simplicity, power, and
		  a certain ineffable grace of design. Higher praise than 'clever',
		  'winning', or even 'cuspy'.

		  The French aviator, adventurer, and author Antoine de Saint-
		  Exupéry, probably best known for his classic children's book
		  "The Little Prince", was also an aircraft designer. He gave us
		  perhaps the best definition of engineering elegance when he said
		  "A designer knows he has achieved perfection not when there is
		  nothing left to add, but when there is nothing left to take away."

	https://www.catb.org/jargon/html/E/elegant.html

	TEXT
	touch -t 197311170853 "$_BASE/$EFILE"

	export MFILE=menuitis
	cat <<-TEXT > "$_BASE/$MFILE"
		menuitis: /men'yoo-i:-tis/, n.

		  Notional disease suffered by software with an obsessively
		  simple-minded menu interface and no escape. Hackers find this
		  intensely irritating and much prefer the flexibility of
		  command-line or language-style interfaces, especially those
		  customizable via macros or a special-purpose language in which one
		  can encode useful hacks.

		  See user-obsequious, drool-proof paper, WIMP environment, for the
		  rest of us.

	https://www.catb.org/jargon/html/M/menuitis.html

	TEXT
	touch -t 199108250527 "$_BASE/$MFILE"

	export IFILE=indent-style
	cat <<-TEXT > "$_BASE/$IFILE"
		indent style: n.

		  [C, C++, and Java programmers] The rules one uses to indent code
		  in a readable fashion. There are four major C indent styles,
		  described below; all have the aim of making it easier for the
		  reader to visually track the scope of control constructs. They
		  have been inherited by C++ and Java, which have C-like syntaxes.
		  The significant variable is the placement of { and } with respect
		  to the statement(s) they enclose and to the guard or controlling
		  statement (if, else, for, while, or do) on the block, if any.

		  K&R style — Named after Kernighan & Ritchie, because the examples
		  in K&R are formatted this way. Also called kernel style because
		  the Unix kernel is written in it, and the 'One True Brace Style'
		  (abbrev. 1TBS) by its partisans. In C code, the body is typically
		  indented by eight spaces (or one tab) per level, as shown here.
		  Four spaces are occasionally seen in C, but in C++ and Java four
		  tends to be the rule rather than the exception.

		    if (<cond>) {
		            <body>
		    }

		  Allman style — Named for Eric Allman, a Berkeley hacker who wrote
		  a lot of the BSD utilities in it (it is sometimes called BSD
		  style). Resembles normal indent style in Pascal and Algol. It is
		  the only style other than K&R in widespread use among Java
		  programmers. Basic indent per level shown here is eight spaces,
		  but four (or sometimes three) spaces are generally preferred by
		  C++ and Java programmers.

		    if (<cond>)
		    {
		            <body>
		    }

		  Whitesmiths style — popularized by the examples that came with
		  Whitesmiths C, an early commercial C compiler. Basic indent per
		  level shown here is eight spaces, but four spaces are occasionally
		  seen.

		    if (<cond>)
		            {
		            <body>
		            }

		  GNU style — Used throughout GNU EMACS and the Free Software
		  Foundation code, and just about nowhere else. Indents are always
		  four spaces per level, with { and } halfway between the outer and
		  inner indent levels.

		    if (<cond>)
		      {
		        <body>
		      }

		  Surveys have shown the Allman and Whitesmiths styles to be the
		  most common, with about equal mind shares. K&R/1TBS used to be
		  nearly universal, but is now much less common in C (the opening
		  brace tends to get lost against the right paren of the guard part
		  in an if or while, which is a Bad Thing).  Defenders of 1TBS argue
		  that any putative gain in readability is less important than their
		  style's relative economy with vertical space, which enables one to
		  see more code on one's screen at once. The Java Language
		  Specification legislates not only the capitalization of
		  identifiers, but where nouns, adjectives, and verbs should be in
		  method, class, interface, and variable names (section 6.8). While
		  the specification stops short of also standardizing on a bracing
		  style, all source code originating from Sun Laboratories uses the
		  K&R style. This has set a precedent for Java programmers, which
		  most follow.

		  Doubtless these issues will continue to be the subject of holy wars.

	https://www.catb.org/jargon/html/I/indent-style.html

	TEXT
	touch -t 200103241305 "$_BASE/$IFILE"

	export TFILE=tty
	cat <<-TEXT > "$_BASE/$TFILE"
		tty: /T-T-Y/, /tit-ee/, n.

		  The latter pronunciation was primarily ITS, but some Unix people
		  say it this way as well; this pronunciation is not considered to
		  have sexual undertones.

		  1. A terminal of the teletype variety, characterized by a noisy
		     mechanical printer, a very limited character set, and poor
		     print quality. Usage: antiquated (like the TTYs themselves).
		     See also bit-paired keyboard.

		  2. [especially Unix] Any terminal at all; sometimes used to refer
		     to the particular terminal controlling a given job.

		  3. [Unix] Any serial port, whether or not the device connected to
		     it is a terminal; so called because under Unix such devices
		     have names of the form tty*. Ambiguity between senses 2 and 3
		     is common but seldom bothersome

	https://www.catb.org/jargon/html/T/tty.html

	TEXT

	export SFILE=spaghetti-code
	cat <<-TEXT > "$_BASE/$SFILE"
		spaghetti code: n.

		Code with a complex and tangled control structure, esp. one using many
		GOTOs, exceptions, or other 'unstructured' branching constructs. Pejorative.
		The synonym kangaroo code has been reported, doubtless because such code has
		so many jumps in it.

	https://www.catb.org/jargon/html/S/spaghetti-code.html

	TEXT
	touch -t 197111031402 "$_BASE/$SFILE"

	export MISSING_FILE=black-art

	export _LESS_KEYS="* Press $(kbd q) or $(kbd Q) to quit
* Press $(kbd j) or $(kbd Down Arrow) to scroll down by one line
* Press $(kbd k) or $(kbd Up Arrow) to scroll up by one line
* Press $(kbd spacebar) to scroll down by one page
* $(kbd h) or $(kbd H) opens the help screen; $(kbd q) closes it again"
}


prologue() {
	[[ -z $DEBUG ]] && clear
	echo
	cat <<-PROLOGUE
	$(_tutr_progress)

	Shell Lesson #1: Running Commands in the Shell

	In the last lesson you learned the basics of using a command shell to
	run simple commands and recover from errors.

	This time you will:

	 * Write and run even more complicated commands
	 * Use the $(cmd less) pager to read large documents in the terminal
	 * Learn the difference between $(bld arguments) and $(bld options)
	 * Find out how to get help in the shell

	This lesson takes around $_DURATION minutes.

	PROLOGUE

	_tutr_pressenter
}


ls_prologue() {
	cat <<-:
	Begin by running $(cmd ls) to see what files are here.
	:
}

ls_test() {
	_tutr_generic_test -c 'ls|dir' -d "$_BASE"
}

ls_hint() {
	_tutr_generic_hint $1 ls "$_BASE"
	cat <<-:

	Run $(cmd ls) to see what files are here.
	:
}

ls_epilogue() {
	_tutr_pressenter
	if [[ ${_CMD[0]} == dir ]]; then
		cat <<-:

		${_R}   ___________    ${_Z}
		${_R}  /           \   ${_Z}     Old habits are tough to break, aren't they!
		${_R} / __ ___ _  __\  ${_Z}      While $(cmd dir) does work, this tutorial expects
		${_R}| / _|  _/ \|_ \| ${_Z}                you to use $(cmd ls) instead.
		${_R}| \_ \||| o | _/| ${_Z}
		${_R}| |__/|| \_/||  | ${_Z}It's more versatile and standard across Unix systems,
		${_R} \             /  ${_Z}      and will serve you better in the long run!
		${_R}  \___________/   ${_Z}

		:
		_tutr_pressenter
	fi
}


echo_prologue() {
	cat <<-:
	Those are some oddly-named files...

	In the last lesson you learned the $(cmd echo) command, which simply prints its
	arguments to the screen.  Recall that $(bld arguments) are what we call the
	words that come after a command's name on the command line.  They serve
	the same purpose as arguments to a function in $(_py).

	It doesn't make a difference to $(cmd echo) if its arguments happen to be names
	of files.  Run $(cmd echo) with these arguments: the names of two files, and
	one word that is not a file

	  $(cmd echo $EFILE $SFILE $MISSING_FILE)
	:
}

echo_test() {
	_tutr_generic_test -c echo -a $EFILE -a $SFILE -a ".*"
}

echo_hint() {
	_tutr_generic_hint $1 echo
}

echo_epilogue() {
	_tutr_pressenter
}


cat_es_prologue() {
	cat <<-:
	Likewise, you can give $(cmd cat) multiple arguments.

	$(cmd cat) the names of those two files, $(path $EFILE) and $(path $SFILE),
	along with the non-file $(cmd $MISSING_FILE)
	:
}

cat_es_test() {
	_tutr_generic_test -f -c cat -a $EFILE -a $SFILE -a $MISSING_FILE -d "$_BASE"
}

cat_es_hint() {
	_tutr_generic_hint $1 cat "$_BASE"
}

cat_es_epilogue() {
	_tutr_pressenter

	cat <<-:

	${_Y}    _.-._   ${_z}
	${_Y}   | | | |_ ${_z}
	${_Y}   | | | | |${_z}
	${_Y}   | | | | |${_z}     Say hi to our familiar friend,
	${_Y} _ |  '-._ |${_z}  the $(_err No such file or directory) error!
	${_Y} \\\`\\\`-.'-._;${_z}
	${_Y}  \    '   |${_z}          Long time, no see!
	${_Y}   \  .\`  / ${_z}
	${_K}jgs${_Y} |    |  ${_z}


	This demonstration illustrates the difference between $(cmd cat) and $(cmd echo):

	 *  $(cmd echo) prints the $(bld names) of files
	 *  $(cmd cat) prints what's $(bld inside) of files

	:
	_tutr_pressenter
}


cat_mmm_prologue() {
	cat <<-:
	You can $(cmd cat) the same filename over and over again.  The result looks
	like one long file.

	Repeat the file $(path $MFILE) three times
	:
}

cat_mmm_test() {
	_tutr_generic_test -c cat -a $MFILE -a $MFILE -a $MFILE -d "$_BASE"
}

cat_mmm_hint() {
	_tutr_generic_hint $1 cat "$_BASE"
}

cat_mmm_epilogue() {
	_tutr_pressenter
}


cat_emts_pre() {
	_LINES=$(tput lines)
}

cat_emts_prologue() {
	cat <<-:
	Let's try that again, but with a different mix of filenames:

	  $(cmd cat $SFILE $MFILE $TFILE $EFILE)
	:
}

cat_emts_test() {
	_tutr_generic_test -c cat -a $SFILE -a $MFILE -a $TFILE -a $EFILE -d "$_BASE"
}

cat_emts_hint() {
	_tutr_generic_hint $1 cat "$_BASE"
}

cat_emts_epilogue() {
	if   (( _LINES < 30 )); then
		cat <<-:
		Most of the text generated by $(cmd cat) scrolled right off the screen.

		You $(bld might) be able to read it by scrolling up, but what a hassle!

		:
	elif (( _LINES < 59 )); then
		cat <<-:
		That much text doesn't fit on the screen!

		The first few lines have scrolled off the top.  You $(bld might) be able
		to read them by scrolling up, but what a hassle!

		:
	elif (( _LINES < 64 )); then
		cat <<-:
		That much text $(bld just barely) fits on your screen!

		What if your terminal window was smaller, or if those files were
		longer?

		:
	else
		cat <<-:
		You have a pretty large terminal, so all of that text fits on your
		screen.  But what if your terminal window was smaller, or those
		files were longer?

		:
	fi

	_tutr_pressenter
}


cat_i_pre() {
	_LINES=$(tput lines)
}

cat_i_prologue() {
	if   (( _LINES > 76 )); then
		cat <<-:
		The file $(path $IFILE) is longer than all of the others, but somehow
		still fits on your screen.  I have to ask, are you really able to read
		this text?  Your font must be so small!

		Anyhow, run this command now:
		  $(cmd cat $IFILE)
		:
	else
		cat <<-:
		$(path $IFILE) certainly will not fit on your screen, but I am going to ask
		you to $(cmd cat) it anyway.
		:
	fi
}

cat_i_test() {
	_tutr_generic_test -c cat -a $IFILE -d "$_BASE"
}

cat_i_hint() {
	_tutr_generic_hint $1 cat "$_BASE"

	cat <<-:

	Run this command to proceed:
	  $(cmd cat $IFILE)
	:
}

cat_i_epilogue() {
	_tutr_pressenter
	cat <<-:

	${_M} _____ _       ____  ____    ${_Z}
	${_M}|_   _| |    _|  _ \\|  _ \\ ${_Z}
	${_M}  | | | |   (_) | | | |_) |  ${_Z}
	${_M}  | | | |___ _| |_| |  _ <   ${_Z}
	${_M}  |_| |_____( )____/|_| \\_\ ${_Z}
	${_M}            |/               ${_Z}
	               ${_C}amirite?${_Z}

	Now you'll learn what to do with text that overflows the screen.

	:
	_tutr_pressenter
}


less_prologue() {
	cat <<-:
	$(cmd less) is a program called a "$(bld pager)".  It is used like $(cmd cat) to display text
	on a terminal.  In contrast to $(cmd cat), $(cmd less) shows one page of text at a
	time and waits for you to press a key before showing the next page.

	In $(cmd less) you can scroll up and down through the text with the $(kbd keyboard);
	your mouse's scroll wheel may or may not work in this program.
	Depending on your outlook, this is not necessarily a bad thing.

	$_LESS_KEYS

	Read the file $(path $IFILE) in $(cmd less).  Use these keys to scan all the way
	through it.  There is a quiz afterward.
	:
}

less_test() {
	_tutr_generic_test -c less -a $IFILE -d "$_BASE"
}

less_hint() {
	_tutr_generic_hint $1 less "$_BASE"
}

less_epilogue() {
	cat <<-:
	Why is it called $(cmd less)?  Because it was preceeded by an earlier
	program called $(cmd more).  $(cmd more) showed a screenful of text at a time, but did
	not support scrolling back.  $(cmd less) is an improved "drop-in" replacement.

	As the saying goes, "$(bld less is more)".

	:
	_tutr_pressenter
}


quiz() {
	local intro="Which indentation style is this?"

	case $_VARIANT in
		"K&R")
			cat <<-:
				$intro

			    if (<cond>) {
			            <body>
			    }

			:
			_tutr_quiz "K&R" Allman Whitesmiths GNU
			;;

		Allman)
			cat <<-:
				$intro

			    if (<cond>)
			    {
			            <body>
			    }

			:
			_tutr_quiz Allman "K&R" Whitesmiths GNU
			;;

		Whitesmiths)
			cat <<-:
				$intro

			    if (<cond>)
			            {
			            <body>
			            }

			:
			_tutr_quiz Whitesmiths Allman "K&R" GNU
			;;

		GNU)
			cat <<-:
				$intro

			    if (<cond>)
			      {
			        <body>
			      }

			:
			_tutr_quiz GNU Whitesmiths Allman "K&R"
			;;

		*)
			cat <<-:
				Hang on!  It's not yet time to take the quiz.
			:
			return 0
			;;
	esac
}

indentation_quiz_pre() {
	declare -a variants=("K&R" Allman Whitesmiths GNU)
	declare -g _VARIANT=${variants[$(( RANDOM % ${#variants[@]}))]}
}

indentation_quiz_prologue() {
	cat <<-:
	I wasn't kidding about the quiz.

	If you get it wrong, re-read $(path $IFILE) with $(cmd less) and try again.

	Run $(cmd quiz) to proceed.
	:
}

indentation_quiz_test() {
	_REREAD_FILE=1
	_RAN_LESS=2
	_TRY_AGAIN=3
	_GAVE_UP=6
	[[ ${_CMD[0]} == quiz && $_RES == 0 ]] && return 0
	[[ ${_CMD[0]} == quiz && $_RES == $_GAVE_UP ]] && return 0
	[[ ${_CMD[0]} == quiz ]] && return $_TRY_AGAIN
	[[ ${_CMD[@]} == "less $IFILE" ]] && return $_REREAD_FILE
	[[ ${_CMD[0]} == less ]] && return $_RAN_LESS
	return $_PASS
}

indentation_quiz_hint() {
	case $1 in
		$_REREAD_FILE)
		cat <<-:
		Now that you've looked at that file again, run $(cmd quiz) to try again.
		:
		;;

	$_RAN_LESS)
		cat <<-:
		Remember to use the arrow keys (or j/k) to scroll up and down to
		find the right section of the document.
		:
		;;

	*)
		cat <<-:
		The important thing here isn't to memorize indentation styles from a
		programming language you aren't using.  This is to
		help you practice navigating a long document in the $(cmd less) pager.

		Run $(cmd less $IFILE) to read up on the indentation types and
		try again.
		:
		;;
	esac
}

indentation_quiz_epilogue() {
	if [[ $_RES == $_GAVE_UP ]]; then
		cat <<-:
		I can't say I blame you for dipping out.
		Nerd fights are exhausting.

		:
	fi

	cat <<-:
	Who knew that indentation could be such a touchy topic?
	Now you know why $(_py) insists on only one indentation style!

	:
	_tutr_pressenter
}


man_cat_prologue() {
	cat <<-:
	While $(cmd less) is handy when you need to read a text file that is too big
	for your screen, usually, you will not directly run it yourself.  You
	will most often use $(cmd less) through other programs that produce too much
	output to be read comfortably in a plain terminal.

	Let's switch gears for a moment, and consider a hypothetical:
	${_Y}  ___  ${_Z}
	${_Y} |__ \ ${_Z} What would you do if I asked you to find a shell
	${_Y}   / / ${_Z} command to add a rule to your computer's firewall
	${_Y}  |_|  ${_Z}
	${_Y}  (_)  ${_Z} (Don't worry, there is no quiz this time)

	:
	_tutr_pressenter

	cat <<-:

	You're probably thinking "I'd $(_Google) it"!  That can work, but consider:

	 * There are many different versions of $(bld shells) and $(cmd commands) out there.
	   How can you be sure the article you found on the web applies to the
	   versions of software on your computer right now?

	 * The command shell long predates the World Wide Web, and more so
	   $(_Google).  How did people figure things out before the internet?

	 * What would you do if the WiFi were down?  Give up and call it a day?

	:

	_tutr_pressenter

	cat <<-:

	The $(bld official) way to get help in the shell is through the system manual
	accessed through the $(cmd man) command.  $(cmd man) takes as an argument the name of
	another command, and displays its manual page using $(cmd less).

	 * When you install programs on your computer, the most up-to-date
	   instructions are installed at the same time.

	 * If $(cmd man) cannot find the manual page for that command, it usually
	   means that program is not installed on that computer.

	 * When programs are installed with their own documentation you can be
	   confident that the instructions will match the code you are running,
	   even if a newer version is available online.

	:
	_tutr_pressenter

	cat <<-:

	Try this out now by opening the manual for $(cmd cat).

	As a reminder, these are the shortcut keys for $(cmd less):

	$_LESS_KEYS
	:
}

man_cat_test() {
	_tutr_generic_test -c man -a cat
}

man_cat_hint() {
	_tutr_generic_hint $1 man
	cat <<-:

	Read the manual for the $(cmd cat) command.
	:
}

man_cat_epilogue() {
	cat <<-:
	Who knew that a simple program like $(cmd cat) could have so many options?

	$(path http://gaul.org/files/cat_-v_considered_harmful.html)

	:
	_tutr_pressenter

	cat <<-:

	You will be referring to manual pages for the remainder of this lesson.
	It may be helpful to open another terminal window to read the manual
	while running commands in this one.

	:
	_tutr_pressenter
}


cat_n_mmm_prologue() {
	cat <<-:
	Command-line arguments beginning with a dash '$(cmd -)' (A.K.A. minus) are
	called "$(bld options)".  Options are not understood by the command as a file
	that should be opened.  Rather, they control the program's behavior.

	There's nothing magic about the dash; it is just a convention because
	people $(bld usually) don't give files names beginning with '$(cmd -)'.  When a
	program sees an argument that begins with '$(cmd -)' it can assume it does not
	refer to a file.  Of course, this causes problems if you accidentally
	create files with weird names, so try not to do that, okay?

	The $(cmd man) page you just looked at shows that $(cmd cat) can take many options.
	There is an option that causes $(cmd cat) to print $(bld line numbers) in front of its
	output.  It's okay if you didn't catch it before; you can re-read the
	manual to find it.

	Then, run $(cmd cat) again using that option with $(path $MFILE) repeated thrice to
	see how many lines in total are output.

	In other words, fill the blank in this command with $(cmd cat)'s line
	numbering option:
	  $(cmd cat __ $MFILE $MFILE $MFILE)
	:
}

cat_n_mmm_test() {
	_LITERALLY=99
	_ALMOST=98
	_READ_MANUAL=97
	[[ "${_CMD[@]}" == "man cat" ]] && return $_READ_MANUAL
	_tutr_noop && return $NOOP
	[[ "${_CMD[@]}" == "cat __ $MFILE $MFILE $MFILE" ]] && return $_LITERALLY
	[[ "${_CMD[@]}" == "cat -b $MFILE $MFILE $MFILE" ]] && return $_ALMOST
	_tutr_generic_test -c cat -a -n -a $MFILE -a $MFILE  -a $MFILE -d "$_BASE"
}

cat_n_mmm_hint() {
	case $1 in
		$NOOP)
			;;

		$_READ_MANUAL)
			cat <<-:
			Did you find what you are looking for?  Let's find out!

			Run $(cmd cat) with the option that puts a line number before each line.
			:
			;;

		$_LITERALLY)
			_tutr_pressenter
			cat <<-:

			Do you always take instructions this literally?

			If you scroll up to the beginning of this command's output, you will
			see this $(_err error) message:
			  $(_err "cat: __: No such file or directory")

			This happened because $(cmd cat) misinterpreted $(path __) as a filename.

			$(bld Replace the blank in this command) with the option from $(cmd cat)'s manual that
			enables line numbering.
			  $(cmd cat __ $MFILE $MFILE $MFILE)
			:
			;;

		$_ALMOST)
			_tutr_pressenter
			cat <<-:

			That was a $(bld really) good guess, but not the option I am looking for.

			Notice that emptly lines were not numbered.  The option I want you to use
			puts numbers in front of every line, even blanks.

			Back to the manual!
			:
			;;
		*)
			_tutr_generic_hint $1 cat "$_BASE"
			;;
	esac
}

cat_n_mmm_epilogue() {
	if [[ $_PLAT != Apple ]]; then
		_tutr_pressenter

		cat <<-:

		$(blu 42)... that number keeps popping up everywhere.
		I wonder if it has any significance?

		:
	fi

	_tutr_pressenter
}


ls_1_pre() {
	unset "_NOOP[ls]"
}

ls_1_prologue() {
	cat <<-:
	$(cmd ls) is much more sophisticated than $(cmd cat), and has many more options.
	Consequently, its man page is longer.  I want you to dive in and find
	a particular option.

	You will have noticed that, by default, $(cmd ls) prints its list horizontally.
	Find an option that lists files $(bld one per line), making a $(bld single column).
	Then run that command.
	:
}

ls_1_test() {
	_READ_MANUAL=97
	[[ "${_CMD[@]}" == "man ls" ]] && return $_READ_MANUAL
	_tutr_noop && return $NOOP
	_tutr_generic_test -c ls -a '^--format=single-column$|^-1$' -d "$_BASE"
}

ls_1_hint() {
	case $1 in
		$NOOP)
			;;

		$_READ_MANUAL)
			cat <<-:
			Did you find what you are looking for?

			Run $(cmd ls) with the option that prints the list of filenames in a
			single column.
			:
			;;

		*)
			_tutr_generic_hint $1 ls

			cat <<-:

			Here are some hints:
			  0. Options can be $(bld digits), not just letters
			  1. $(bld Scroll down) - the answer is not near the top
			  2. You're looking for a $(bld short option) (starts with one '$(cmd -)'), and
			     not a $(bld long option) (they begin with two '$(cmd --)')

			When in the manual page viewer, use these keys to navigate:

			$_LESS_KEYS

			Run $(cmd ls) with the option that list file names one per line,
			in a $(bld single column).
			:
			;;
	esac
}

ls_1_epilogue() {
	if [[ "${_CMD[@]}" = *single-column* ]]; then
		cat <<-:
		Good work!  But that was a lot of typing.

		$(cmd ls) has a shorter option that does the very same thing: $(cmd "-1").
		Isn't that short and sweet?

		I'll let you get away with $(cmd "--format=single-column") this time,
		but for the rest of the lesson I will only accept $(cmd "-1").

		Just looking out for your carpal tunnels :)

		:
	else
		cat <<-:
		Good work!

		:
	fi
	_tutr_pressenter

	cat <<-:

	Besides being accessible even when the internet is down, the biggest
	advantage of man pages is that they $(bld exactly) match the software on your
	computer right now.

	You must $(bld always) be aware of version mismatches when looking up help
	online.  It is way too easy to find obsolete or inaccurate information
	with a search engine.  Mac users will find that Linux-specific webpages
	give advice that doesn't work on their computer, and vice versa.

	Man pages also don't have ads, so there's that.

	:
	_tutr_pressenter
}


ls_1S_prologue() {
	cat <<-:
	Let's try a few more of these.

	$(cmd ls) has another option that lists files by $(ylw size), largest first.
	Use it along with '$(cmd "-1")' to display the files in one column.
	The order that you give these options to $(cmd ls) doesn't matter.
	:
}

ls_1S_test() {
	local pattern='^ls -S1$|^ls -1S$|^ls -1 -S$|^ls -S -1$'
	_READ_MANUAL=99
	_MAN_NO_PAGE=95
	_MAN_WRONG_PAGE=94