7 ms·
Manpages aren't all the same quality. Look at the manpage for find(1) https://linux.die.net/man/1/find https://linux.die.net/man/1/find An enormous page full o
by LordShredda 3y ago
Manpages aren't all the same quality. Look at the manpage for find(1) https://linux.die.net/man/1/find https://linux.die.net/man/1/find
An enormous page full of switches and options, yet if you're a beginner it's basically useless. You're just looking for a simple example of how to search for a file. find . -i -name <regex> is NOT mentioned anywhere, you have to figure it out yourself. And if you mess it up, your terminal gets flooded.
Contrast with grep(1) https://linux.die.net/man/1/grep https://linux.die.net/man/1/grep which is short, simple, and easily searchable with keywords
Manpages are very useful, having offline documentation is great. But it is more of a specification reference than a manual.
- msravi 3y agoI've found tldr (https://tldr.sh/ https://tldr.sh/) very useful for quick lookups - basically gives examples with short descriptions, which is very often mostly what's needed.
- epiccoleman 3y agoMy favorite is cheat.sh, which is a similar thing to tldr, but the best part about cheat is that you can just `curl cheat.sh/ln` (or whatever command) and get the cheat sheet on any system. I use this all the time.
- jerf 3y ago"An enormous page full of switches and options, yet if you're a beginner it's basically useless." Maybe 30 years ago you could learn through manpages but today that's how all the man pages of all the useful commands look. If you think grep is nice it would be the exception; for me it is indeed short, simple and easily searchable, but too terse for a beginner to learn with easily. (Plus even the regex documentation only documents grep mode, not egrep or pgrep or anything else.) Very useful in its own way, but most man pages are useless for learning. I am disappointed at how few man pages take the opportunity to have a useful selection of "the 10 most popular things to do with this command" but web search has filled in reasonably decently. You do still have to understand the basics of how shell works, though, because most of them aren't quite what you want today and honestly a fair number of them aren't even what the poster thought they were. I am also in the habit of making sure that I understand every command line switch before I copy & paste a command off the internet, again, because many of them aren't what you need today. I don't always mean in a malicious manner, but things like either do or do not follow HTTP redirects in curl may or may not matter to you today, but the poster may be in the habit of setting it one way or another for no reason relevant to you.
- markus_zhang 3y agoYeah man! Scenarios! Those documentations rarely bother with scenarios, which is all newbies need!
- fsckboy 3y agowithin a magpage that section is called EXAMPLES there are not enough of them now, they used to be more prevalent
- markus_zhang 3y agoYeah some have examples but many don't. I think maybr that's not the purpose of manpages though, more suitable for a cookbook.
- shrimp_emoji 3y agoMan pages are pre-Internet Age help StackOverflow is Internet Age help ChatGPT is post-Internet Age help In ascending order of helpfulness (modulo LLM confabulation)
- ilyt 3y agoAnd in descending order of correctness. ChatGPT inherited "confidently wrong" and "misunderstanding question and then answering to question they misunderstood" from stackoverflow
- charlieflowers 3y agoI wonder if chatgpt will start “closing” questions as “not a good fit for its Q&A format,” or “too opinionated,” or “a duplicate” of something that is acutely unrelated. Actually, this seems to be a case where chatgpt is smarter than the humans.
- bombcar 3y agoChatGPT will not be able to hallucinate options to find and grep and ls because they all use every single letter of the alphabet.
- paulddraper 3y agogrep's prerequisite is to understand regexes.
- m463 3y agoThis goes deeper, since understanding grep regexes involves understanding quoting. This means not only how regexes distinguish between literals and control characters, but how the shell distinguishes and passes on characters to the regex that grep receives as an argument. I think regex quoting is one of the major stumbling blocks of comprehension. Even after decades using regexes, I still stumble (especially when my regexes are used in the shell, in emacs, in python re.match, etc...)
- cutler 3y agoFriedl's "Mastering Regular Expressions" is one of the best books I've ever read and started my Unix journey via Perl and Emacs.
- JdeBP 3y agoWhich rather reinforces the point of the headlined article: People actually learn a lot of stuff when they start out from tutorials, guides, handbooks, and whatnot; not from purely reading reference doco. I started out with books, too. Later people would have started with the likes of TLDP. I suspect that the author is right that most people started with guides/handbooks/tutorials, even the ones who later on convince themselves that they only read reference doco.
- cutler 3y agoO'Reilly's bestiary had an exceptional line-up of Unix classics in the early 2000s.
- yoyohello13 3y agoOne thing I love about the Sway Window Manager is how awesome the man pages are. They are clearly written and contain great examples.
- meinersbur 3y agoDo you mean the other way around? The manpage of find contains examples, including searching for files by name. This alone make the manpage somewhat usable for beginners. The grep manpage does not have any examples. The grep manpage spends much explaining regex and environment variables, find more on options. Both manpages are searchable, what makes the grep manpage more searchable?
- jbverschoor 3y agoI learned Unix by reading the FreeBSD handbook.
- mjw1007 3y agoThat's because find's principal documentation is in info. https://www.gnu.org/software/findutils/manual/html_mono/find.html https://www.gnu.org/software/findutils/manual/html_mono/find...
- jonnycomputer 3y agoAnd that points to another problem.
- floren 3y agoStallman's pathetic devotion to the ITS online help system?
- jonnycomputer 3y agoman some-tool info some-tool some-tool --help just help me dammit some-tool
- nvy 3y agofind(1) is a classic example. The first two or three pages are of essentially zero practical use. I open the manual, skim the first page, no obvious clues about how to actually use `find`, so my next step is always to go to web search. I've got a thousand things to do that are better uses of my time than reading 20 pages of arcane documentation that may or may not answer my question.
- JdeBP 3y agoOr: Manpages aren't all the same quality. Look at the manpage for util-linux find(1): * https://manpages.debian.org/bullseye/findutils/find.1.en.html https://manpages.debian.org/bullseye/findutils/find.1.en.htm... Contrast with the manpage for NetBSD find(1), where something similar to what you mention is in fact the very first example in the EXAMPLES section: * https://man.netbsd.org/find.1 https://man.netbsd.org/find.1 Compare with the manpage for Illumos find(1), where like util-linux it leaps into -exec and expressions in brackets with the second example: * https://illumos.org/man/1/find https://illumos.org/man/1/find Then remember that some operating systems come with handbooks and guides, and if one wants a tutorial for beginners, reference doco is not the place to start at all. So next contrast with the SCO UnixWare users guide, which also starts off with find file by name and print: * http://uw714doc.xinuos.com/en/FD_files/Moving_and_managing_files.html#Loc_files_not_in_curr_dir http://uw714doc.xinuos.com/en/FD_files/Moving_and_managing_f... Then remember that GNU has a long-standing antipathy to man pages, and that actually one should have magically known the name "findutils": * https://www.gnu.org/software/findutils/manual/html_node/find_html/Overview.html#Overview https://www.gnu.org/software/findutils/manual/html_node/find... And there's also this thing that someone decided to call The Linux Documentation Project which has a book titled _Introduction to Linux_: * https://tldp.org/LDP/intro-linux/html/sect_03_03.html#sect_03_03_03 https://tldp.org/LDP/intro-linux/html/sect_03_03.html#sect_0...
- ilyt 3y agoNetBSD doesn't look all that more helpful, you just get to examples sooner because it has far less options The NetBSD examples also only document what command do, while the util-linux sometimes go into details of why, like when describing how exactly the time directive works and why `-mtime 0` shows files from last 24 hours.
- 400thecat 3y ago> https://man.netbsd.org/find.1 https://man.netbsd.org/find.1 "find -- walk a file hierarchy" what an idiotic summary
- xcdzvyn 3y ago
- m463 3y agoI disagree - the find manpage is significantly better than the grep manpage because of one aspect: EXAMPLES Examples are critical to comprehension, are immensely practical, yet are often viewed as fluff.
- motohagiography 3y agoAfter about 30y of using *nix of one kind or another, I only use the EXAMPLES section of man pages as I know that most writers write to sound out their ideas, and the first bits are worse than useless. If there isn't one, I go to stackoverflow. The same style extends to library documentation, where you have functions and arguments with types and no other context. It's basically for posterity.
- stodor89 3y agoAgreed, lack of examples was my biggest gripe with the manly pages when I was a Linux newbie. The most frustrating part is, you know they do it on purpose, so that you have to read the entire thing! News flash, I'm here because I'm stuck and want to get unstuck ASAP, not because I'm bored and want to learn the intricate details of find/grep/whatever.
- ilyt 3y agoSoftware documentation is an art. Right balance of exact operation of software and examples, put in order that's useful in normal usage, and explanation for the more complex parts
- jerrysievert 3y agocurrent macOS man pages are kind of off-putting, even for someone who has been using c and unix for decades. I mean, really, what is this? InFILE In* fopen(Inconst Inchar In* Inrestrict Inpath, Inconst Inchar In* Inrestrict Inmode); Inconst InFILE In* Inrestrict Inpath?! FILE *fopen(const char *, const char *mode); it's like looking at a ton of gibberish and trying to figure out what it says. it doesn't match the languages, it doesn't appear to match any standards. I learned a lot from man pages in the 80's and 90's, and if I had to try to learn now from something like this, I'd likely just throw up my hands and choose another career.
- JdeBP 3y agoMy educated guess is that something is trying to italicize various keywords, and whatever text processing is going on isn't working, but producing bogus "In" literal text instead. .I is the "an" macro for italics, after all.
- JdeBP 3y agoCompare what one sees when the text processing works, and what parts are italicized. * https://tty0.social/@JdeBP/110427220635184435 https://tty0.social/@JdeBP/110427220635184435 It even prettifies those ``'' quotes, notice. This is vanilla older FreeBSD man, using groff, but actually allowing groff to do the things that it is capable of.
- vulcan01 3y agoThis matches what I see using less as manpager and every terminal I have installed on MacOS (Apple Terminal, kitty, alacritty+Tmux, iTerm).
- astrange 3y agoLooks fine here. https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/fopen.3.html https://developer.apple.com/library/archive/documentation/Sy...
- thefilmore 3y agoThe POSIX man pages tend to be much more approachable: https://manp.gs/posix/1/find https://manp.gs/posix/1/find
- fsckboy 3y ago> find . -i -name <regex> is NOT mentioned anywhere you've got some typos here, it's not mentioned because... that's not how find works. find has no -i like grep ; to ignorecase you use -iname ; and for name regular expression matching you need to use find . -iregex <regex> # (or -regex) find . -iname <pattern> # (uses wildcards ? \*) cheers :)
- LordShredda 3y agoSee stuff like this is what frustrates me. Why can't the manpage tell me that? Thanks though.
- nmz 3y agoFind is the worst example given it breaks the do one thing and do it well motto of unix. (and you can do one thing and do it well), After discovering dmenu's stest and googles walk, most times I just need a { walk $PWD | stest -f | rg } and I'm done. Maybe you need more, in which case, instead of find, you should run stat with the output formatted to json/csv and then filter using your preferred csv method or jq.
- wesapien 3y agoPre chatgpt, for most things tldr gets me what I need. These days yeah, chatgpt goes a long way.
- penguin_booze 3y agoI was pleased with how expect's man page [0] oriented me (instead of "it's all there, go figure"): > Commands are listed alphabetically so that they can be quickly located. However, new users may find it easier to start by reading the descriptions of spawn, send, expect, and interact, in that order. [0] https://linux.die.net/man/1/expect https://linux.die.net/man/1/expect