Some feedback you probably won't hear from the HN crowd:
Give more context to the site for initial visitors. Its going to be more obvious to those who visited from HN but not to those who stumbled upon it somehow. A little blurb at the top saying this is a reference site for bash scripting syntax and maybe why you saw the need for such a thing would do ease people into the site a bit.
I hate the popup at the bottom, I will hesitate to use the site again because of that (just like many of us avoid news sites with pesky popups), Its a major turn-off. Probably an unpopular opinion around here, but just maybe make a note at the bottom regarding the privacy stuff unless there are legal reasons not to (I'm not up on all the regulations) If you can't avoid it, make it way less intrusive.
Overall its really nice and I love to see better documentation made around old-school linux/bash tools and syntax as I often feel the documentation can be unwieldy with a lot of knowledge assumed. +1 to examples as others have said. Keep it up! :)
This is great feedback. I have removed the popup, I've had the suspicion that people may find it annoying and you and a few others have now confirmed it. Maybe I'll find some other use for it. I despise these things myself also, which is a bit funny lol. It turned into a "can I do it" rather than a "should I do it"-thing when the idea first crossed my mind..
I'll see if I can come with some non-disruptive way of adding some context to the site upon entering it.
It would definitely be helpful to have more context. I know some bash, but I'm far from an expert. The first thing I see on the page is a list of flags, but no clue what commands these flags are used with. A few usage examples would help a lot.
For example "-e checks if files exists" How? -e filename ? This doesn't work?
As a nostalgic side note, I'm not even that old, and I miss when the Internet looked like this. Just regular folks learning HTML and writing about something they find interesting. These days, everything looks like it was built in a Wix or Squarespace factory.
This section is missing stuff like setuid, sticky bit, extended attributes, etc. (SELinux stuff and setgid? I'm not sure if there's more.) For example, `ls -ld /tmp` shows `drwxrwxrwt`, `ls -l /bin/sudo` shows `-rwsr-xr-x`.
> History Expansion
To this section, it might be good to add `!$`. Also maybe a quick overview on word designators, to cover syntax like `!:^`, `!:2`, `!:<asterisk>`, etc. There's also modifiers, like `!$:h` to return the (h)ead of a path that's the last argument of the previous command, etc.
> Bash Globbing
> @ Matches exactly one of a given pattern
It might be better to put these extended glob ones as @(pattern-list) for example, just like it is on the manpage. Putting it just like @ next to ? or <asterisk>, implies that it just goes like that alone.
> Overview of Bash Symbols
> $(( )) is used for saving the output of arithmetic.
I guess you could save it, but you can also pass it directly to where you need it. I wouldn't call `echo $(( 1 + 2 ))` saving it.
> $[] deprecated integer expansion construct which is replaced by (( ))
No, it's replaced by `$(())`.
EDIT: Removed the part about the file types. You have that covered. However, you wrote
> c Special file
> b Block device
They're both special files. `c` is for character devices.
Very cool, thanks for sharing. Here's some trivial suggestions.
- There's a lot of info here, so I think you should aim for curation and conciseness, rather than completeness. For example, in File Test Operators, your first two entries (effectively, the first two entries a visitor sees) is `-e` and `-a`, both of which you describe as "File exists", though for the latter, you write: "(identical to -e but is deprecated and outdated)". Is there any reason for `-a` to be included if it's not useful? When I use a cheatsheet, I just want what's most useful, not a full historical reference.
- This is a minor thing, and very much imho, but it was a little distracting to see Times New Roman (or rather, the Mac default serif font) as the base font for the descriptive text, which is a font that I associate with an unstyled (i.e. unpolished) website. IMHO , it looks a bit better in Georgia, or a sans-serif like "Helvetica Neue". Again, just imho, I'm sure others might vehemently disagree.
- The associated twitter handle looks like @shellmagic1 – why not use the handle @shellmagicxyz, which is currently unused?
- I'll be making a section for deprecated stuff and move everything of that sort into one section. Good suggestion.
- I've added a bunch of new fonts to the site, just now. It's a temporary selection of fonts - but include nicer ones like Source Code Pro for code, and a sans-serif for headings and navigation bar.
- Thank you very much for mentioning that. That's a way nicer handle!
I always find the context switch to get to a website jarring, and really really love tools that give me documentation on the command line. For example, I can type "go doc foo.Bar" and instantly read the docs for foo.Bar (where foo is usually resolved to example.com/some/go/package/foo, based on what is in go.mod and installed on the system). So for this, I would really like bash's built-in help to show me all this stuff.
They did a 10% implementation of what would be good:
$ help [
[: [ arg... ]
Evaluate conditional expression.
This is a synonym for the "test" builtin, but the last argument must
be a literal `]', to match the opening `['.
But it doesn't know how to dive into [ and show docs for the operators, i.e., "help [ -e" doesn't work. The [ documentation also doesn't tell you what options are available, and of course [ doesn't implement --help (but, of course, /bin/[ does. And people say computers are hard to use! Psh!).
So anyway, if this could all be fixed with a command-line utility, that would be wonderful. It is likely that if I ever need to remember what [ -e does, I'll "man [" or failing that "info bash" or failing that, give up and write the program in go so at least I can work from some documentation.
> It is likely that if I ever need to remember what [ -e does
I realize a lot of folks consider the context switch to paper to also be jarring, but this is why I like analog reference works. I remember roughly how far in to the book the table of all those obscure flags are, and the book more or less falls open to it, because I've been there before.
> "help [ -e" doesn't work. The [ documentation also doesn't tell you what options are available
Well, knowing that `[` is the same as `test`, you can `man test` to see the available options.
Personally, I avoid `[` for `[[`. To see the options for that, I do `man bash`, then type `/\[\[`, hit Enter, and press `n` a few times until the list of options appears. It's in the "CONDITIONAL EXPRESSIONS" section.
Almost everything shown in this site is available in bash's manpage.
GNU's `ls` has most of its documentation in `info ls`.
There's no need to turn to websites. All documentation is available locally from the command line. If anything, it just requires a bit of skill in searching. With `man`/`less`, you search with `/` like I showed; in `info`, you search with <Ctrl-s>.
Also, `command [ --help` does work. It's not the same as the built-in, but it should be mostly the same.
> I always find the context switch to get to a website jarring, and really really love tools that give me documentation on the command line.
Heh, as a person who mostly writes Clojure code, I always find the context switch to go to the command line jarring and really really love tools that give me the documentation straight in my editor!
I understand the concern, but [ is one of those idiosyncratic shell builtins that you eventually get used to and the help does point you toward maybe typing "help test". But, yeah it should probably say it explicitly or just append the "help test" content when it prints "help [".
It's a reference site about Bash scripting, and it's being improved each day since it still has some rough edges. But I'm starting to like the result on desktop resoulution. Next up is improving the CSS for low-res devices and adding toggable color-themes by clicking some radio-buttons or something :-)
Readit News
Give more context to the site for initial visitors. Its going to be more obvious to those who visited from HN but not to those who stumbled upon it somehow. A little blurb at the top saying this is a reference site for bash scripting syntax and maybe why you saw the need for such a thing would do ease people into the site a bit.
I hate the popup at the bottom, I will hesitate to use the site again because of that (just like many of us avoid news sites with pesky popups), Its a major turn-off. Probably an unpopular opinion around here, but just maybe make a note at the bottom regarding the privacy stuff unless there are legal reasons not to (I'm not up on all the regulations) If you can't avoid it, make it way less intrusive.
Overall its really nice and I love to see better documentation made around old-school linux/bash tools and syntax as I often feel the documentation can be unwieldy with a lot of knowledge assumed. +1 to examples as others have said. Keep it up! :)
I'll see if I can come with some non-disruptive way of adding some context to the site upon entering it.
For example "-e checks if files exists" How? -e filename ? This doesn't work?
As a nostalgic side note, I'm not even that old, and I miss when the Internet looked like this. Just regular folks learning HTML and writing about something they find interesting. These days, everything looks like it was built in a Wix or Squarespace factory.
This section is missing stuff like setuid, sticky bit, extended attributes, etc. (SELinux stuff and setgid? I'm not sure if there's more.) For example, `ls -ld /tmp` shows `drwxrwxrwt`, `ls -l /bin/sudo` shows `-rwsr-xr-x`.
> History Expansion
To this section, it might be good to add `!$`. Also maybe a quick overview on word designators, to cover syntax like `!:^`, `!:2`, `!:<asterisk>`, etc. There's also modifiers, like `!$:h` to return the (h)ead of a path that's the last argument of the previous command, etc.
> Bash Globbing
> @ Matches exactly one of a given pattern
It might be better to put these extended glob ones as @(pattern-list) for example, just like it is on the manpage. Putting it just like @ next to ? or <asterisk>, implies that it just goes like that alone.
> Overview of Bash Symbols
> $(( )) is used for saving the output of arithmetic.
I guess you could save it, but you can also pass it directly to where you need it. I wouldn't call `echo $(( 1 + 2 ))` saving it.
> $[] deprecated integer expansion construct which is replaced by (( ))
No, it's replaced by `$(())`.
EDIT: Removed the part about the file types. You have that covered. However, you wrote
> c Special file
> b Block device
They're both special files. `c` is for character devices.
- There's a lot of info here, so I think you should aim for curation and conciseness, rather than completeness. For example, in File Test Operators, your first two entries (effectively, the first two entries a visitor sees) is `-e` and `-a`, both of which you describe as "File exists", though for the latter, you write: "(identical to -e but is deprecated and outdated)". Is there any reason for `-a` to be included if it's not useful? When I use a cheatsheet, I just want what's most useful, not a full historical reference.
- This is a minor thing, and very much imho, but it was a little distracting to see Times New Roman (or rather, the Mac default serif font) as the base font for the descriptive text, which is a font that I associate with an unstyled (i.e. unpolished) website. IMHO , it looks a bit better in Georgia, or a sans-serif like "Helvetica Neue". Again, just imho, I'm sure others might vehemently disagree.
- The associated twitter handle looks like @shellmagic1 – why not use the handle @shellmagicxyz, which is currently unused?
- I've added a bunch of new fonts to the site, just now. It's a temporary selection of fonts - but include nicer ones like Source Code Pro for code, and a sans-serif for headings and navigation bar.
- Thank you very much for mentioning that. That's a way nicer handle!
They did a 10% implementation of what would be good:
But it doesn't know how to dive into [ and show docs for the operators, i.e., "help [ -e" doesn't work. The [ documentation also doesn't tell you what options are available, and of course [ doesn't implement --help (but, of course, /bin/[ does. And people say computers are hard to use! Psh!).So anyway, if this could all be fixed with a command-line utility, that would be wonderful. It is likely that if I ever need to remember what [ -e does, I'll "man [" or failing that "info bash" or failing that, give up and write the program in go so at least I can work from some documentation.
I realize a lot of folks consider the context switch to paper to also be jarring, but this is why I like analog reference works. I remember roughly how far in to the book the table of all those obscure flags are, and the book more or less falls open to it, because I've been there before.
Well, knowing that `[` is the same as `test`, you can `man test` to see the available options.
Personally, I avoid `[` for `[[`. To see the options for that, I do `man bash`, then type `/\[\[`, hit Enter, and press `n` a few times until the list of options appears. It's in the "CONDITIONAL EXPRESSIONS" section.
Almost everything shown in this site is available in bash's manpage.
GNU's `ls` has most of its documentation in `info ls`.
There's no need to turn to websites. All documentation is available locally from the command line. If anything, it just requires a bit of skill in searching. With `man`/`less`, you search with `/` like I showed; in `info`, you search with <Ctrl-s>.
Also, `command [ --help` does work. It's not the same as the built-in, but it should be mostly the same.
Heh, as a person who mostly writes Clojure code, I always find the context switch to go to the command line jarring and really really love tools that give me the documentation straight in my editor!
For all people like me addicted to this kind of reference websites full of information, check out http://hyperpolyglot.org/unix-shells (and all pages on http://hyperpolyglot.org/ actually).
http://zsh.sourceforge.net/Doc/Release/Expansion.html