News for hackers. Stuff that matters.
Re:Toybox: All-in-one Linux command line by aasasd on Saturday September 25, 2021 @04:10AM (#28651428)
As I discovered in practice, it seems to be a trend with authors of such small-size software to also forgo any kind of documentation: what options are supported by specific commands, what behaviours they exhibit (which sometimes differs between GNU and BSD). The ‘usage’ messages are also terse and cryptic to the max. Doubly baffling when the audience of the software is supposedly corporations building their userspace. Do the authors sell the docs on the side, or what?

Anyway, for users trying to do stuff with these utils, the available paths seem to be either finding StackOverflow answers from others who already messed with their own systems and survived, or being the first to do the trial-and-error.

Re:Toybox: All-in-one Linux command line by Already__Taken on Saturday September 25, 2021 @06:26AM (#28651978)
this is what I think powershell has contributed. you literally can't make a utility that doesn't have documentation because it's generated from the code.
Re:Toybox: All-in-one Linux command line by jml7c5 on Saturday September 25, 2021 @04:23AM (#28651483)
It appears that each command is documented at the top of its respective source file. Though I may be misunderstanding and you mean that that documentation is insufficient.

Regardless, I agree that there should be a proper man page with more detail.

Re:Toybox: All-in-one Linux command line by 1vuio0pswjnm7 on Saturday September 25, 2021 @05:49AM (#28651836)
Its been said that the best documentation is source code. For UNIX I have always found this is solid advice. Whats nice about small programs, such as this one, is that its more feasible to use the source code as documentation.

"Anyway, for users ..."

Ah, thats me. I am a user. I personally love terse and cryptic, i.e., minimising the number of keys I have to press. IME, multicall binaries like the OP presume some pre-existing knowledge of how to use the utilities they contain. It seems nonsensical to complain about missing documentation given the purpose of a multicall binary is to conserve space.

With BSD, the utilities in crunched binaries are generally the same ones, i.e., use the same source code, as in one in the userland. With GNU busybox, they are not, and one needs to read the source code to understand the differences.

Even if I can figure out how to use a program from reading documentation I still look at the source code before using it for the first time.

Re:Toybox: All-in-one Linux command line by ghoward on Saturday September 25, 2021 @10:33AM (#28653494)
I understand where you are coming from, but just because a program is small does not mean it does not need documentation.

My `bc` is in toybox, but I have put extensive effort into documenting it. [1] I have even documented it for future maintainers. [2]

[1]: https://git.yzena.com/gavin/bc/src/branch/master/manuals/bc/...

[2]: https://git.yzena.com/gavin/bc/src/branch/master/manuals/dev...

Re:Toybox: All-in-one Linux command line by aasasd on Saturday September 25, 2021 @06:55AM (#28652094)
I keep wondering what it is that makes C programmers especially antisocial and obnoxious. Is it like in that joke:

Father calls his small son to him, pours a shot of vodka and tells him to drink it. The son drinks, then makes a face and says in repulse: “Eurgh, it's disgusting!”

The man replies: “Yeah, you probably thought your dad drinks honey, did you?”

Re:Toybox: All-in-one Linux command line by dang-guefever on Saturday September 25, 2021 @07:09AM (#28652150)
Individuals who prefer legible, honest signalling and understanding to doing double-work for ignorant, ungrateful people. Yeah, it's a mystery.

In short: "Programs are meant to be read by humans, and only incidentally for computers to execute."

Re:Toybox: All-in-one Linux command line by maydup-nem on Saturday September 25, 2021 @08:40AM (#28652691)
That quotes simply means that you shouldn't write spaghetti code, and that another _programmer_ should be able to read it.

Quite clearly, it doesn't carry a meaning of: "hey, every user now has to become a proficient reader of whatever languages this software is written in."

Re:Toybox: All-in-one Linux command line by aasasd on Saturday September 25, 2021 @07:38AM (#28652313)
Ah yes, the famed clarity and readability of C, where people are so entrenched in the belief that the compiler limits identifiers to seven characters or whatever, and in the aversion to typing out a single word in full, that they still build whole new languages with module, function and variable names looking like alphabet vomit. And with ungoogleable (ironically) language names to top it off.
Re:Toybox: All-in-one Linux command line by 1vuio0pswjnm7 on Saturday September 25, 2021 @11:01AM (#28653688)
I exclude man pages when I create systems with crunched binaries where I want to save space. The man pages are always available online. Its like djb's programs. They just refer the user to his website. I am not a programmer. I am the user. The small systems I create are for me and no one else, so naturally I make them according to personal preferences.
Re:Toybox: All-in-one Linux command line by maydup-nem on Saturday September 25, 2021 @06:05AM (#28651891)
> Its been said that the best documentation is source code

fuck you. it's a myth perpetrated by lazy programmers, who can't be bothered to spend an hour or two writing a comprehensible usage manual, while otherwise EVERY USER IS GUARANTEED to spend MORE just figuring out how to BEGIN using his crap. It's only forgivable for the simplest of self-explanatory /API/ calls, but /nothing/ in userspace.

Re:Toybox: All-in-one Linux command line by dang on Saturday September 25, 2021 @08:50PM (#28657423)
Posting like this will get you banned here, so please don't do that.

If you wouldn't mind reviewing https://news.ycombinator.com/newsguidelines.html and taking the intended spirit of the site more to heart, we'd be grateful. In particular, we don't want flamewars, and you've unfortunately already posted quite a few flamewar comments. Can you stick to thoughtful, curious comments instead? That's the kind of conversation we're trying for here. Note that that includes being respectful to whomever you're talking with, regardless of how wrong they are or you feel they are.

Re:Toybox: All-in-one Linux command line by forty on Saturday September 25, 2021 @07:02AM (#28652124)
I think your comment can be improved by removing your first two words, which brings nothing to this conversation.
Re:Toybox: All-in-one Linux command line by gadrev on Saturday September 25, 2021 @09:43AM (#28653136)
Somehow I agree with both parent and you. Ah, life is never black and white...
Re:Toybox: All-in-one Linux command line by maydup-nem on Saturday September 25, 2021 @07:47AM (#28652362)
It's too often that developers adopt this attitude that I have to resort to vulgarity. They are practically forcing my hand there.
Re:Toybox: All-in-one Linux command line by craftinator on Saturday September 25, 2021 @05:42PM (#28656461)
The "my actions are THEIR fault" excuse only works in The Manchurian Candidate.
Re:Toybox: All-in-one Linux command line by croon on Saturday September 25, 2021 @06:38AM (#28652035)
Edit out the expletive and replace the caps with ~ before and after and I'll agree with everything else in the comment.
Re:Toybox: All-in-one Linux command line by matthewh806 on Saturday September 25, 2021 @07:19AM (#28652206)
what a tiresome bore you sound
Re:Toybox: All-in-one Linux command line by dang on Saturday September 25, 2021 @08:51PM (#28657432)
Please don't cross into personal attack or name-calling, regardless of how bad another comment is or you feel it is.

https://news.ycombinator.com/newsguidelines.html

Re:Toybox: All-in-one Linux command line by spockz on Saturday September 25, 2021 @07:10AM (#28652154)
Documentation != user guide or manual. Manual are part of the documentation. And it is still true that the source code is the best documentation, ideally the source code can be used to automatically generate the docs. But overall documentation and things like ADR will hardly ever find their way into the source so require writing then externally.
Re:Toybox: All-in-one Linux command line by maydup-nem on Saturday September 25, 2021 @07:44AM (#28652347)
> Documentation != user guide or manual

It is within this comment section:

> forgo any kind of documentation: what options are supported by specific commands, what behaviours they exhibit

Re:Toybox: All-in-one Linux command line by dang-guefever on Saturday September 25, 2021 @07:15AM (#28652182)
I too am unskilled at navigating unfamiliar codebases and demand clifnotes because my time as a user is more valuable than yours as a programmer. these gift horses are AWFUL