Hacker News Reader

Comment by LordShredda | Hacker News Reader

Manpages aren't all the same quality. Look at the manpage for find(1) 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 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.

View on HN

"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.

the openbsd manuals usually have examples. you can see how compact https://man.openbsd.org/grep.1 is compared to the gnu grep manual.

i've been using https://git.causal.agency/exman/about/ to compare linux and bsd manpages, and it has saved me an incredible amount of time looking things up.

perhaps gnu's manpages suffer because they focused so much effort on their info pages.

Are info pages still a thing? I remember being very confused by them back when I started out with Linux, and eventually just stopped trying to understand how they worked.

They are, but my impression is that only Emacs users use them to some extent. (Emacs has a built-in info reader that is better than the standalone client, and ships mainly info pages as its documentation.) Outside of Emacs, I’d say very few people know info is even a thing, and I remember some Linux distributions also stripped info pages from packages since everyone used man pages.

More than better, people doesn't know how to use GNU Info correctly.

In fairness, if one were to come to more, pg, or less with no prior knowledge of the conventions, the madness of some of the character choices would be just as grating.

Ironically, this sort of stuff -- the basic conventions like qhjkl0^$G + CRFFBSSPC keyboard navigation and :/? prompt modes -- is exactly what one initially learns from guides, tutorials, other people in IRC, and whatnot, long before coming to reference doco. The _Introduction to Linux_ book at TLDP covers the bare essentials of these conventions, q, b, and SPC, in the "quickstart" chapter 2.

* https://tldp.org/LDP/intro-linux/html/sect_02_03.html

Every time I could not find and answer to a question in a man page and consulted info, it was a waste of time. I like info, really, but the remark at the end of most GNU man pages to look at the info pages is misleading at best.

For emacs stuff, yes, it's very convenient. I remember once upon a time, Python docs were available in info as well. When you have good documentation available in info, it's very nice.

I remember offering to make a PR w/ examples for something when I was a junior dev and was politely told that they didn't want examples. I assumed - and still assume - that this was a generational difference in what people expected competence to look like.

While this attitude made sense pre-internet, reading about every switch for common use cases is just not realistic today. Maybe if the number of command-line programs were less, and the complexity of each command was significantly less, I could see how it would be done, but not today.

Yeah man! Scenarios! Those documentations rarely bother with scenarios, which is all newbies need!

within a magpage that section is called EXAMPLES

there are not enough of them now, they used to be more prevalent

Yeah some have examples but many don't. I think maybr that's not the purpose of manpages though, more suitable for a cookbook.

tealdear and tldr seems to do "top 10 most useful things you can do with this command"

Man 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)

There is a pre-internet and Internet pre-Stackoverflow bit. Called O'reilly books.

Learning to program for example Perl. I had the learning book, the reference book and the cookbook. learning I did once, the reference had post its on it and was on my work desk. The cookbook was more the facebook type you read it on the toilet.

They had books on everything that were the industry standard. DNS, Apache, Javascript, ... The revised them regularly. For Js had the 1st, 2nd, 3rd edition. I know this sounds all ancients like real paper books. But even work had O'reilly subscription so you could order what you need.

For me it was O'reilly books, man pages. But lets not forget when you installed Linux like RedHat (not fedora yet) you could install the linux howtos. Oh boy did I learn a lot from them too: https://tldp.org/HOWTO/HOWTO-INDEX/howtos.html

Finally there was IRC if you were stuck but this was off course the internet stage. I just went online to ask a question, dialup was expensive ;)

> (modulo LLM confabulation)

As of now, there is no LLM without confabulation, so your third item is effectively "hypothetical fantasy ChatGPT that we hope will be available some time in the future", not the actual tools we have right now.

And in descending order of correctness.

ChatGPT inherited "confidently wrong" and "misunderstanding question and then answering to question they misunderstood" from stackoverflow

I 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.

ChatGPT will not be able to hallucinate options to find and grep and ls because they all use every single letter of the alphabet.

A recent example: I used ChatGPT 4 to draft an mkvmerge command - take 2 video files, and merge them by only copying certain audio and subtitle tracks from the second file into the first file.

The resulting command looked good at first sight, something like „mkvmerge -o output.mkv first.mkv —-no—video -s 1 -a 2 -a 3 -a 4“. The problem here is that there can only be one -a flag, so it should have been „-a 2,3,4“ instead. But mkvmerge didn’t really care and just discarded every -a flag except the last one. So I ended up with only one of the audio tracks copied over. I only noticed when I actually checked the resulting file that it had less audio tracks than it was supposed to.

This would not have happened to a human after studying the man page - the documentation is very clear about the -a flag and I have no idea what led ChatGPT to come to the conclusion it did.

The lesson here is not to anthropomorphize ChatGPT. It didn't "conclude" anything. Based upon a corpus that includes tonnes of humans writing rubbish on the WWW, it came up with plausibly human-appearing rubbish that can fool humans. GIGO would apply, except that one can remix non-garbage into garbage with suitable statistical processes, we have now (re-)discovered. (-:

I think in this case it wasn’t GIGO but rather a too weak signal/noise ratio for mkvmerge. IMO there’s a subtle distinction.

> 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 :)

See stuff like this is what frustrates me. Why can't the manpage tell me that? Thanks though.

Or:

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.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

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

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_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...

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_0...

NetBSD 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.

> https://man.netbsd.org/find.1

"find -- walk a file hierarchy"

what an idiotic summary

That's a little inflammatory. Could you provide constructive input on your reasoning behind that statement? I personally found it a simple, concise explanation of what find is for.

imagine you don't know how find works or what it does. Does that sentence make any sense?

Yes. A few seconds of thinking does the trick.

"file hierarchy" - Something to do with my file organization?

"walk" - Most programmers are familiar with trees.

Oh, we are walking through the file tree!

That's because find's principal documentation is in info.

https://www.gnu.org/software/findutils/manual/html_mono/find...

And that points to another problem.

Stallman's pathetic devotion to the ITS online help system?

man some-tool

info some-tool

some-tool --help

just help me dammit some-tool

find(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.

I 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.

After 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.

Agreed, 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.

current 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.

My 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.

Compare what one sees when the text processing works, and what parts are italicized.

* 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.

This matches what I see using less as manpager and every terminal I have installed on MacOS (Apple Terminal, kitty, alacritty+Tmux, iTerm).

I don't think that's a macOS bug. Your terminal emulation might be borked.

What terminal are you using? I just tested on Terminal.app and iTerm2.app -- `man fopen` looks correct on both.

The following should be equivalent, but might perform differently for you depending on what part of your config is bad:

  cat /usr/share/man/man3/fopen.3 | nroff -man | more

iterm2.app - but I also use fish as my shell

TERM=xterm-256color and LESS_TERMCAP_us=In

Your LESS_TERMCAP_us is the issue here; it's literally putting "In" wherever an underline is supposed to start.

As others have noted, the 'In' looks like a rendering bug with whatever terminal emulator you're using. Otherwise it looks pretty normal: `fopen (const char *restrict filename, const char *restrict mode)` looks like a perfectly good C function, and (if you already know C) it's easy to see the parts that don't look like they belong.

Looks fine here. https://developer.apple.com/library/archive/documentation/Sy...

amazing how web pages look different than terminal output :)

Looked fine in two terminal apps too, but you can't copy paste that!

I learned Unix by reading the FreeBSD handbook.

My man.

The FreeBSD Handbook was an amazing resource.

I still reference it.

I 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

Find 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.

I had never heard of "walk". Is there some link to read more about it?

Found it: https://github.com/google/walk

One thing I love about the Sway Window Manager is how awesome the man pages are. They are clearly written and contain great examples.

Do 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?

The POSIX man pages tend to be much more approachable: https://manp.gs/posix/1/find

Software 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

I've found tldr (https://tldr.sh/) very useful for quick lookups - basically gives examples with short descriptions, which is very often mostly what's needed.

My 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.

grep's prerequisite is to understand regexes.

This 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...)

Friedl's "Mastering Regular Expressions" is one of the best books I've ever read and started my Unix journey via Perl and Emacs.

Which 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.

O'Reilly's bestiary had an exceptional line-up of Unix classics in the early 2000s.

Pre chatgpt, for most things tldr gets me what I need. These days yeah, chatgpt goes a long way.

Reply on news.ycombinator.com