How are we referring to systems - Linux-like? *nix?

On zsh systems the history file might be smaller. Replace ~/.bash_history with $HISTFILE

Let's break this down. First, we use the -E flag to tell grep to use Extended Regular Expressions. This allows us to use some clever constructs to search for text.

I know what you want to say, but factually this is wrong. You can use history | grep "[0-9]+ man" to achieve exactly the same effect ('use some clever constructs').
Suggestion: Use the history | grep "\[0-9\]+ man" version first, explain briefly it's a different dialect and then introduce the '-E' switch to get back to familiar territory (history | grep -E "[0-9]+ man").

For familiar uses, grep becomes a

Potential typo. 'users'?

See threads at:

https://news.ycombinator.com/item?id=31830676

There's a lot of comments indicate where some of the content is wrong or could be clearer; earlier chapters could use a scrub.

Should we have a samples folder everyone can clone to follow along with?

And then all screenshots can be based on this sample folder?

And should we show this using Windows or Linux or Mac? Or alternate between them all?

There are a lot of shells out there which can be a difficult landscape for newcomers to navigate. And while bash, zsh and powershell are popular and well known, there are also many others around: https://en.wikipedia.org/wiki/Comparison_of_command_shells

Perhaps adding a chapter on the history, a small comparison and practical examples could be useful? + once you get deeper into some of these shells you might also want to look into plugin managers e.g. for zsh - zplugin, antigen, antibody, zgen, zplugin, etc.

Create a really nice animation a bit like https://starship.rs/ also look at a yes no question, 'become a shell expert' or something. This would make the home page less dry.

Summaries for each section, highlighting what has been covered. This is also for people who want to skip a section, and just skim what was covered.

The introduction states at the moment that the book is for anyone who uses a shell regularly. In fact, given the most recent structure it is actually for anyone. So the introduction should be updated to explain that it is more generally useful.

Describes who should read it, what you will learn, and any pre-requisites. Make each section header in the TOC a link to the overview.

The 'change in parentheses' section can be simplified as per:

#301

This would be a nice thing to explain as it saves some keystrokes

The playground is the folder effective-shell-playground and has all of the files used in the samples etc. It would be great to be able to publish this as an artifact, or even just stick it on the website in a known location on deployment, so anyone can just curl or wget it down.

Actually, zipping it and sticking it on the website is probably the best way, rather than faffing with release tags or additional artifacts.

This is not the most pressing thing in the world, but is a little annoying. I would like to have clean addresses when the structure is complete, just makes it a bit easier for sharing and cleaner. And changing is painful when the page already has disqus comments.

In the C style loops section, there is this paragraph.

This loop structure uses three arithmetic expressions to run the loop. The first is in 'initialise' expression, this is typically used to setup the initial state of the loop. The second is the 'conditional' expression, this is used to check whether the loop is complex. The third is the 'iterate' expression, this is evaluated after the loop commands are completed.

Why is complex used here? Is it a typo?

Could be interesting to look into Shopify/Printify as an option to sell physical prints of the shell 'fly on the command line' poster or other reference posters.

I haven't tracked down the root of the issue, but this line

is being interpreted incorrectly by Docusaurus. Specifically, [email protected]_ is generating a non-italicized, valid [email protected] email address as a mailto link. GFM is handling it fine, though.

It's a very minor issue, but it detracts from the point of the sentence. I can imagine fixing it by choosing a different bit of formatting, or perhaps adding a leading space, but I'm not familiar with Docusaurus' quirks, so it's hard to advise a solution.

For work with grep, awk, tr and so on, it would be useful to have some larger and more complex text files. We want files to demo:

1. Things like error logs (which we grep)
2. (add more details as needed)

Is it worth having a section on "Why Linux" in the book? This might be useful for Windows users...

In the "Navigating the Command Line" section, there are a bunch of commands described as "deleting" things. Also in [website/content/docs/section1/1-navigating-the-command-line/images/command-line.png the image] commands are subdivided into "Move" and "Delete".

The thing is, readline does not actually delete! More accurately, does "not only" delete: it rather kills (comparable to an—enhanced—cut command).

The short version is that, as a result of killing instead of merely deleting, you can later yank the killed text back (comparable to paste). (The longer version is that there exists a kill ring and that opens up a whole other can of worms. :-) But it's awesome! And worth mentioning! At the very least, "delete" is simply … too simplistic. ;-) )

Would be useful to include a guide on how to install the Windows Subsystem Linux.

Would be so cool to be able to curl effective.sh to read the book in the shell 😄

Docoaurus is looking better each time I check it:

https://v2.docusaurus.io/

V2 is explicitly moving to content support, i.e. not just docs but any content site (e.g. books). It looks like out-of-the-box it might look cleaner and be more structured.

This would be an excellent theme:

https://themes.gohugo.io/hugo-book/

https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-ideal-image

Would be good to integrate site-wide

Would be cool to be able to:

curl effective-shell.sh/playground | bash

To get the samples!

For the book, we should also decide definitively where the sample or playground live (e.g. ~/effective-shell), this will make all of the samples easier.

stdin is short for ‘standard input’ - it's where many programs read their input from
stdout is short for ‘standard output’ - it's where many programs write their output to
stderr is short for ‘standard error’ - it's where some programs write error messages to
The wording feels strange. What does 'some' / 'many' mean? Is this relevant?

I would rather write something like

"stdout" - intended for regular output
"stderr" - intended for error messages
(annotation: Some programs don't follow this convention, e.g. )
Since this is beginner-level documention I'd stick with the intention.
You could offer an 'advanced example' (using grep -v) to ignore output from misbehaving programs.

tangent: You could elaborate why piping in memory is better then writing to files. (-> no need to clean up afterwards!)

Redirect it into the file with descriptor (&) 1 - which is standard output
Could be more clear on what the ampersand is doing. (Maybe add an annotation that 2>1 would redirect into a file with name '1'. This would hopefully stick and help users debug if their command doesn't do what it should, but '1' files are showing up in their directory.)

Another bonus - pipelines save intermediate files from being created

I think it also would be worthwhile to note the example on piping stderr and stdout to a single file. Why the following doesn’t work and does work, respectively.
sh script.sh 2>&1 >> log_file.txt # Doesn't work
sh script.sh > log_file.txt 2>&1 # Does work

head -100 5_GB.csv > small_manageable.csv

Note some common conventions for stdin, e.g.:

• curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | apt-key add -

These notes above might also go into the 'weird stuff' chatper (i.e. the chapter on things which are not consistent and are gotchas)

Consider a section on <<<:

https://unix.stackexchange.com/questions/572424/retrieve-both-http-status-code-and-content-from-curl-in-a-shell-script

Maybe a chapter 'advanced redirection?'

Grep should be an example for output, with a link to a later chapter.

https://github.com/dwmkerr/effective-shell/blob/main/docs/02-core-skills/09-job-control/images/kill-job.gif

I noticed the page linking this has a broken gif link:

https://effective-shell.com/part-2-core-skills/job-control/#cleaning-up-jobs

Chapter 5 has a 'hack on' readme section which shows a little more on tracing system calls, but is not linked to from the main page.

It makes it too big...

Hello!

I've been reading this repository and I really appreciated. I would like to contribute by translating to portuguese (Brazil). I think this would be a good improvement for this project.

A little thing - would be nice to make the copyright text smaller and maybe show the current git sha at the bottom of the page (to debug if the right version is loaded in the browser)

It would be great to have a 'share' button for each page.

It might be useful to also show which commands are introduced in each chapter (for example, moving around would show cd, pushd, popd).

If you look at a title like 'The If Statement' the chapter seems boring.

But what about if the chapter started with:

By the end of this chapter you'll know why:

• You should put quotes around variables in an if statement
• The magic shell syntax to write a test command with just two characters

I.e. not giving the game away, but hinting to new and advanced users what they might discover.

In Chapter 8 - The Power of Readline: It lists the Node.js REPL as an example of a program that uses GNU Readline, but Node actually uses it's own JS parser which ignores the .inputrc file. If you need alternative example, Ruby's REPL (irb) uses Readline.

The website should include the copyright notice at the bottom of each page.

Create a summary of the book, blow-by-blow for each chapter.

Note on:

1. Fonts
2. System setup
3. Erratia

Comment from the share on LinkedIn:

One thing I would add is to quickly mention hidden files when introducing the -a flag for ls, since users might come across those at this point and wonder what they are.

Great suggestion from here: https://www.linkedin.com/feed/update/urn%3Ali%3Aactivity%3A6660383783935705088/?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A6660383783935705088%2C6663312143833804800%29&midToken=AQG-nz-C47s2lg&trk=eml-email_notification_single_commented_on_your_update_01-notifications-1-hero%7Ecard%7Efeed&trkEmail=eml-email_notification_single_commented_on_your_update_01-notifications-1-hero%7Ecard%7Efeed-null-2q7p3b%7Ek9ti6xyf%7E2n-null-voyagerOffline

We need the appropriate license for the site and content.

The print edition will contain boxes as callouts. It would be good to have a semantic representation of this in the raw markdown content.

Hugo Book uses 'Hints':

https://themes.gohugo.io//theme/hugo-book/docs/shortcodes/hints/

These could work quite nicely. A good example of what might be a hint online (or a box in a book) would be the 'where does the name grep come from' in Chapter 12.

It would be useful to add a TOC to each chapter, or maybe even a global TOC

Is this intentional?

docs/03-manipulating-text/15-slice-and-dice-text/index.md

The format on the preview windows is correct, as the above screenshot shows.

The format on the website is incorrect, as the above screenshot shows.

Need to make it clear in the intro, front cover and back cover that this is for both Bash and ZSH (as ZSH is the default on MacOS and I believe also one or two Linux distros).

Then in any place where the functionality will differ, use a box to call out the differences. But make it clear that the demos work the same for both shells unless otherwise stated.

In Chapter 12 - The Terminal: This might be a bit pedantic, but terminal programs usually refer to themselves a 'terminal emulator' to distinguish themselves from a hardware terminal.

Setup an appropriate contributor guide. This will need to take into account the license, and detail how copyright and contributions work. Until this is completed contributions should not be taken as I'm not sure of the licensing issues.