Hacker News Reader

Hacker News

Comment by LeoPanthera | Hacker News Reader

Full thread

LeoPanthera

Some other useful man pages:

hier - Explains the filesystem layout

ascii - An ASCII table

builtins - Things your shell does without external binaries

signal - Includes a table of all the signal numbers

View on HN

I consider myself quite proficient on the command line; intermediate would be fair to say.

However, I just can’t really parse man pages. I’ve never sat down and just figured out the numbering scheme and how to efficiently read/parse them.

Occasionally I’ll read a man page online, but a quick blog post seems to be an easier reach, or even GPT these days.

For example, hier: https://linux.die.net/man/7/hier

—

Also, a good opportunity to complain about -h/--help flags not being universally recognized by bins.

The source of the manpages on die.net is always questionable to me. I've found they're often out of date or for questionable versions of software. https://manpages.debian.org/ has all the relevant man pages and is always up to date. (and it allows you to pick between different providers of the page)

Look at `man man`, the numbers are explained:

https://www.man7.org/linux/man-pages/man1/man.1.html

Do you feel the same way about reading technical documentation or specifications vs. digested explanations and instructions in general? Most man pages are probably closer to the former in spirit.

Nope. I enjoy reading the official docs for languages like Python (narrative or API). For Java I'm fine reading signatures; it's OK. I've not found a lot of good docs in that language, TBH. Even TypeScript can be alright, though I find myself navigating to definition a lot. That said, it's highly proj. dependent. E.g. fp-ts is hard to parse, though perhaps rewarding and succinct when you make progress.

I've written my fair share of documentation, too. E.g.: http://python-forge.readthedocs.io

It might be that manpages lack links, and it's hard to hop back and forth, as I can't set markers like in vim, so my controls are just up/down.

I've found the pager search function useful in some cases when navigating man pages. At least in less, '/' does forward search, and '?' does backward search.

Navigating longer man pages does seem to be somewhat clumsy, though, and finding things in something massive such as the gcc man page takes work. I'm probably just used to it enough that I don't always even realize it.

There's also man(1) for the table of what the (#) section numbers mean.

>builtins - Things your shell does without external binaries

My OpenSUSE install doesn't have builtins. I just look in bash(1).

>signal - Includes a table of all the signal numbers

Specifically signal(7)

I consider the linux-man-pages project (usually simply "man-pages" in most linux distributions) to be the single best reference manual for UNIX C programming. It has extensive descriptions, examples, warns about libc/platform differences, and allows discovery of new/similar functions through the SEE ALSO section at the end of the page.

https://man7.org/linux/man-pages/dir_section_3.html

Not useful exactly but I occasionally enjoy typing `man -a tee` into my terminal. Not even an Easter egg but it usually cheers me up (jury's out on du ./gong)

`man ascii` changed my life. No more ad-ridden ascii table websites. Glorious.

The problem with man pages is that they are hard to discover if you don't know the name.

The canonical answer to your problem is APROPOS(1). It searches man pages for keywords. Say you remember there was a man page describing the filesystem hierarchy, you'd run:

    $ apropos "filesystem hierarchy"
    hier (7)             - description of the filesystem hierarchy
    $ man 7 hier
    # you're off!

now you "just" need to remember that apropos is a thing...

The only problem with `apropos` is that it returns so many irrelevant results:

  $ apropos 'count lines' | wc -l
     167

  $ apropos 'count lines' | head
  AllPlanes(3), BlackPixel(3), WhitePixel(3), ConnectionNumber(3), DefaultColormap(3), DefaultDepth(3), XListDepths(3), DefaultGC(3), DefaultRootWindow(3), DefaultScreenOfDisplay(3), DefaultScreen(3), DefaultVisual(3), DisplayCells(3), DisplayPlanes(3), DisplayString(3), XMaxRequestSize(3), XExtendedMaxRequestSize(3), LastKnownRequestProcessed(3), NextRequest(3), ProtocolVersion(3), ProtocolRevision(3), QLength(3), RootWindow(3), ScreenCount(3), ScreenOfDisplay(3), ServerVendor(3), VendorRelease(3) - Display macros and functions
  EVP_PKEY_asn1_find(3ssl), EVP_PKEY_asn1_find_str(3ssl), EVP_PKEY_asn1_get_count(3ssl), EVP_PKEY_asn1_get0(3ssl), EVP_PKEY_asn1_get0_info(3ssl) - enumerate public key ASN.1 methods
  EVP_PKEY_meth_get_count(3ssl), EVP_PKEY_meth_get0(3ssl), EVP_PKEY_meth_get0_info(3ssl) - enumerate public key methods
  OCSP_REQUEST_new(3ssl), OCSP_REQUEST_free(3ssl), OCSP_request_add0_id(3ssl), OCSP_request_sign(3ssl), OCSP_request_add1_cert(3ssl), OCSP_request_onereq_count(3ssl), OCSP_request_onereq_get0(3ssl) - OCSP request functions
  OCSP_resp_find_status(3ssl), OCSP_resp_count(3ssl), OCSP_resp_get0(3ssl), OCSP_resp_find(3ssl), OCSP_single_get0_status(3ssl), OCSP_resp_get0_produced_at(3ssl), OCSP_resp_get0_signature(3ssl), OCSP_resp_get0_tbs_sigalg(3ssl), OCSP_resp_get0_respdata(3ssl), OCSP_resp_get0_certs(3ssl), OCSP_resp_get0_signer(3ssl), OCSP_resp_get0_id(3ssl), OCSP_resp_get1_id(3ssl), OCSP_check_validity(3ssl), OCSP_basic_verify(3ssl) - OCSP response utility functions
  OPENSSL_malloc_init(3ssl), OPENSSL_malloc(3ssl), OPENSSL_zalloc(3ssl), OPENSSL_realloc(3ssl), OPENSSL_free(3ssl), OPENSSL_clear_realloc(3ssl), OPENSSL_clear_free(3ssl), OPENSSL_cleanse(3ssl), CRYPTO_malloc(3ssl), CRYPTO_zalloc(3ssl), CRYPTO_realloc(3ssl), CRYPTO_free(3ssl), OPENSSL_strdup(3ssl), OPENSSL_strndup(3ssl), OPENSSL_memdup(3ssl), OPENSSL_strlcpy(3ssl), OPENSSL_strlcat(3ssl), CRYPTO_strdup(3ssl), CRYPTO_strndup(3ssl), OPENSSL_mem_debug_push(3ssl), OPENSSL_mem_debug_pop(3ssl), CRYPTO_mem_debug_push(3ssl), CRYPTO_mem_debug_pop(3ssl), CRYPTO_clear_realloc(3ssl), CRYPTO_clear_free(3ssl), CRYPTO_malloc_fn(3ssl), CRYPTO_realloc_fn(3ssl), CRYPTO_free_fn(3ssl), CRYPTO_get_mem_functions(3ssl), CRYPTO_set_mem_functions(3ssl), CRYPTO_get_alloc_counts(3ssl), CRYPTO_set_mem_debug(3ssl), CRYPTO_mem_ctrl(3ssl), CRYPTO_mem_leaks(3ssl), CRYPTO_mem_leaks_fp(3ssl), CRYPTO_mem_leaks_cb(3ssl), OPENSSL_MALLOC_FAILURES(3ssl), OPENSSL_MALLOC_FD(3ssl) - Memory allocation functions
  PKCS5_PBKDF2_HMAC(3ssl), PKCS5_PBKDF2_HMAC_SHA1(3ssl) - password based derivation routines with salt and iteration count
  RSA_set0_key(3ssl), RSA_set0_factors(3ssl), RSA_set0_crt_params(3ssl), RSA_get0_key(3ssl), RSA_get0_factors(3ssl), RSA_get0_crt_params(3ssl), RSA_get0_n(3ssl), RSA_get0_e(3ssl), RSA_get0_d(3ssl), RSA_get0_p(3ssl), RSA_get0_q(3ssl), RSA_get0_dmp1(3ssl), RSA_get0_dmq1(3ssl), RSA_get0_iqmp(3ssl), RSA_get0_pss_params(3ssl), RSA_clear_flags(3ssl), RSA_test_flags(3ssl), RSA_set_flags(3ssl), RSA_get0_engine(3ssl), RSA_get_multi_prime_extra_count(3ssl), RSA_get0_multi_prime_factors(3ssl), RSA_get0_multi_prime_crt_params(3ssl), RSA_set0_multi_prime_params(3ssl), RSA_get_version(3ssl) - Routines for getting and setting data in an RSA object
  TIFFFieldPassCount(3tiff) - get whether to pass a count to TIFFGetField/TIFFSetField
  TIFFFieldReadCount(3tiff) - get number of values to be read from field

Well, staple utilities typically have short names, so sorting the results by name length might help:

    $ apropos count lines | awk '{print length($1), $0}' | sort -n | head
    2 gc (1)               - count graph components
    2 nl (1)               - number lines of files
    2 rg (1)               - recursively search the current directory for lines matching a pattern
    2 sa (8)               - summarizes accounting information
    2 wc (1)               - print newline, word, and byte counts for each file
    3 box (3x)             - create curses borders, horizontal and vertical lines
    3 cvt (1)              - calculate VESA CVT mode lines
    3 gtf (1)              - calculate VESA GTF mode lines
    3 rev (1)              - reverse lines characterwise
    3 sum (1)              - checksum and count the blocks in a file

Side-note, there are a bunch of neat utilities here I didn't know about!

> The canonical answer to your problem is APROPOS(1). It searches man pages for keywords.

`apropos` only searches short descriptions. But `man -K` let's you search all conent of man pages.

> now you "just" need to remember that apropos is a thing...

man has apropos built-in (`man -k`) and calls out `apropos` directly in its help message and its man page, so `man man` will reveal that as well as `man --help`.

some BSD ones:

sysexits(3) - meaningful exit codes

style(9) - C coding style

style.Makefile(9) - other coding styles (here, Makefile)

dang definitely woulda loved this 20 years ago when i was just starting out with linux. very neat thanks

also man bash. you will learn what >() and <() mean

I was never able to read the entirety of man bash though

Maybe I'm using the wrong search regex, but I can't find an explanation for >() or <() in `man bash`, `man builtins` or `man bash-builtins`.

It's in bash(1) under "Process Substitution" — https://manpages.debian.org/bookworm/bash/bash.1.en.html#Pro...

If your MANPAGER is less, you can type ^R (CTRL+R) in the search prompt (/) to make it interpret the search string literally (disable regular expressions). As noted in less(1).

Reply on news.ycombinator.com