From 97a80d04489dd74c6d756eac75f9355b315d3b40 Mon Sep 17 00:00:00 2001 From: hachem Date: Thu, 3 Sep 2026 00:59:51 +0200 Subject: docs: man page and README --- README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c924903..18edd85 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,68 @@ # just a fucking manual -jafm is just a convenient utility program that searches through your man pages instead of making you find the man page yourself. I find it genuinely insane how illiterate the default `man` command can be. I was making a simple HTTP server in C, and, as you know, I wanted to look up the man page for `sockaddr_in`. But every single time I tried `man sockaddr_in`, `man` would go: `No manual entry for sockaddr_in`. And this *should* work, because it works on Linux. But, as it so happens, I am not on Linux all the time. +`jafm` searches through **all your man pages** for a symbol, figures out which +page actually documents it, and opens it for you. -The documentation for `sockaddr_in` was there. It was inside another man page. So naturally, I had to somehow figure out which random man page contained the thing I was looking for. jafm fixes that. It just looks through **all your man pages**, tells you where it found your query, gives you a selector, and opens the man page for you. +I find it genuinely insane how fucking illiterate the default `man` command can be. I was making a simple HTTP server in C and wanted the man page for `sockaddr_in`. Every single time I tried `man sockaddr_in` it went: `No manual entry for sockaddr_in`. And this *should* work, because it works on Linux. But, as it so happens, I am not on Linux all the time. The docs for `sockaddr_in` were right there, inside another page (`inet`). So I had to somehow guess which random man page contained the thing I was looking for. `jafm` fixes that. It reads every page, ranks the hits so the real one is on top, shows you a picker with a live preview, and opens whatever you choose. ```sh -$ jafm sockaddr_in +$ jafm sockaddr ``` That's it. I find it genuinely unacceptable that this is not an already solved issue. -## License +## What you get + +`jafm` searches every page in your `manpath`, in parallel, in a fraction of a second. It **ranks by relevance** so the page that actually documents your symbol floats to the top, tells you *what* it found and its **kind** (`sockaddr_in (struct)`), and gives you an **interactive picker** with a live `man` **preview** on the side and the match highlighted in the page. + +## Usage + +```text +$ jafm --help +jafm 0.1.0 - just a fucking manual + +greps your whole manpath for a symbol and opens the page that actually +documents it, because `man ` gives up way too easily. + +usage: jafm [-1] [-l] [-e] [-t type] [-j threads] + jafm [-v | -h] + +options: + -1, --first open the best match without asking + -l, --list just print what it found, open nothing + -e, --exact match the symbol as a whole word only + -t, --type KIND only show matches where the symbol is a KIND + (struct, union, enum, typedef, function) + -j, --jobs N scan with N worker threads (default 8) + -v, --version print version and bail + -h, --help print this and bail + +by hachem +``` + +In the picker: `↑`/`↓` or `k`/`j` to move, `Enter` to open, `q` to bail. Pipe +its stdin instead of a tty and it drops to a numbered prompt. + +```sh +$ jafm sockaddr # pick from the list +$ jafm -1 getentropy # open the best match straight away +$ jafm -t struct -l sockaddr # every struct named *sockaddr*, printed +$ jafm -e -1 inet # whole word, open the winner +``` + +## Build +Needs a C17 compiler, `zlib`, and pthreads. Nothing else. + +```sh +$ sudo make install # -> /usr/local/bin + man page +$ make install PREFIX=~/.local # or somewhere without sudo +``` -jafm is licensed under the MIT License. See [LICENSE](LICENSE) for more information. +It really is one file, so if you don't want the Makefile: + +```sh +cc -O2 -std=c17 jafm.c -o jafm -lz -lpthread +``` + +## License +`jafm` is licensed under the MIT License. See [LICENSE](LICENSE) for more. -- cgit v1.3