It would be nice if the same energy went into submitting patches to the
owners of the man pages to improve their EXAMPLES sections.
The difference is in the barrier to entry. For example, I’ve often found mistakes in Mac’s man pages, but can’t even be arsed to figure out the whos, hows and wheres of it.
Similarly, another project by a Googler recently asked me to sign Google’s open source contributor agreement. For being such a simple thing to do, it turned out they want my physical address, phone numbers etc. there. Sorry, I’d rather have the project implement the patch I contributed on their own than yield to such insanity.
Sure, there will be those cases. There’s plenty more where it’s just as easy to submit a patch for. I’m fairly certain that all of the entries on the home page, for example, wouldn’t be a problem.
Or, making more usable versions of those commands, with intuitive arguments within arms reach, like ag and ack have done for grep.
ag and ack are far more specialised, though. They both are aimed at
searching source code, while grep is a generalised text search tool. I
do agree that in most cases, programs could stand with an improved UI
(GNU tools, I’m looking at you).
Reminds me of http://cheat.errtheblog.com, but is that even still maintained? (The last gem version is a year old, and the website has broken links.)
A whole flame war is going on at HN about whether using “bro” is okay or not. Honestly, I can’t decide for myself, either.
I don’t really know what to think either. I guess it could remind people of the whole “brogrammer” meme and be exclusionary in that way. But “bro” has never really been a loaded or offensive word.
Also, from the thread, it seems like the author intended “bro” to stand for “brochure”, which I think is actually a pretty hilarious play on words. Oh well, I guess if you make a joke these days someone’s bound to get offended. Now back to more productive things.
I think this is a good idea, I often find myself frustrated at man pages for not providing decent examples. While I enjoy the depths man pages often go into, sometimes an example usage section is all you really want.
Also I think the community maintenance and “wisdom of the crowds” approach of the “bropages” is a nice touch too.
The only slight irritant for me is the dependency on Ruby, the start up time to spin up the runtime is grating, especially when compared to opening man pages is almost instantaneous
I like the speed of it. It seems much easier to me most of the time to see a few quick examples of common use-cases than to wade through a man page listing every single option and what it does, with no examples until 20 pages in.