Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Yeah, but it's easy to skip once you know what it is and that you understand it already. For someone who doesn't, having it present may be vital.

In my opinion, the same is true of computing - as a mentor, especially when working with folks who don't come to programming from a "typical" background, there's a lot of basic context that has to be conveyed precisely because so much of our docs assume they can leave out all the stuff that "everybody knows".




The worst is where you assume a vanilla implementation of some basic functionality, so you skip the explanation, but actually, there's a quirk inside that you only discover after scratching your head for a while.

Newbies are lucky in this way, that they don't have even a mistaken reason to skip reading the basics.


Unix/ Linux man pages are really hard to understand because of this


True, but they make up for it by being also very difficult to use in their intended role as aides-memoire, both because of the way they're written and because the relatively primitive format provides no aid to search or navigation.


I find `man X | grep Y` actually works OK, and the "see also" at the bottom is quite helpful for finding related information.

But if I don't already know exactly what I'm looking for, it's hard to use. It's really difficult to "learn about" how to open sockets if I can't remember sockaddr_t exact spelling or the right header to include.


On a BSD, try ‘man -Otag=l ls’ or ‘:tl’ (from less) for e.g. ls -l. This also works for larger man pages: ‘man -Otag=OCRNL termios’. More specifically, this requires the mandoc man implementation, which is also available on Linux — it’s what I prefer for all my machines.

tl;dr: it’s groff(1), not the -man and -mdoc formats, which is primitive (in this sense).




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: