(no title)
simoncion | 2 days ago
Yes. It's the syntax alongside prose explaining the behavior in detail. Go give it a read.
If you want documentation that's done up in the "modern" style, then you'll prefer that one-page cheat sheet that that guy made. I find that "modern" documentation tends to leave it up to each reader to discover the non-obvious parts of the behavior for themselves.
> I find Python ... easier to understand.
Have you read the [0] docs for Python's 'subprocess' library? The [1] docs for Python's 'multiprocess' library? Or many of the other libraries in the Python standard library that deal with nontrivial process and I/O management? Unless you want to underdocument and leave important parts of the behavior for users to incorrectly guess, such documentation is going to be much larger than a cheat sheet would be.
[0] ...twenty-five pages of...
[1] ...fifty-nine pages of...
goku12|2 days ago
Bold of you to assume that I or the others didn't. I made my statement in spite of reading it. Not because I didn't read it. So my opinion is unchanged here.
The point here is simple. Documentation is a very important addition. But you can't paper over other deficiencies with documentation, especially if you find yourself referring the same documentation again and again. It's an indication that you're dealing with an abstraction that can't easily be internalized. Throwing the book at everyone isn't a good solution to every problem.
> Have you read the [0] docs for Python's 'subprocess' library? The ...
Yes, I have! All of those. Their difference with bash documentation is that you get the idea in a single glance. I spend much less time wondering how to make sense of it all. Python's abstractions are well thought out, carefully selected, consistently and orthogonally implemented and stays out of the way - something I can hardly say about bash. If that's not enough for you, Python has something that bash lacks - PEPs. The documents that neatly outline the rationale behind their decisions. That's what a lot of programmers want to know and every programmer should know.
Fun fact: The Epstein files contain a copy of the bash manual! Of course they weren't involved in his crimes. It was just one of the documents found on his system. A sysadmin is believed to have downloaded it for reference. But it's telling that it wasn't the Python manual, or the Perl manual, or something else. Meanwhile, I don't really think that Epstein was running Linux on his system.
> Unless you want to underdocument and leave important parts of the behavior for users to incorrectly guess, such documentation is going to be much larger than a cheat sheet would be.
If properly designed, such expansive documentation would be unnecessary, as they would be obvious even with the abstractions. For example when you use a buffer abstraction in modern languages, you have a fairly good idea what it does and why you need it, even though you may not care about its exact implementation details. That's the sort of quality where bash and other POSIX shells fail on several counts. In fact, check how many other shells break POSIX compatibility to solve this problem. Fish and nushell, for example.
"The developer is too lazy to read the documentation" isn't the appropriate stance to assume when so many are expressing their frustration and displeasure at it. At some point, you have to concede that there are genuine problems that cannot be blamed on the developer alone.
simoncion|2 days ago
> Their difference with bash documentation is that you get the idea in a single glance.
> If properly designed, such expansive documentation would be unnecessary, as they would be obvious even with the abstractions.
What is it the kids say? "Tell me you don't make use of 'multiprocessing', 'subprocess', and other such inherently-complicated modules without telling that you don't..."? Well, it's either that, or you that often use them, and rarely use bash I/O redirections... because, man, the docs for just the 'subprocess.Popen' constructor are massive and full of caveats and warnings.