A new, comprehensive man(7) system, all commands documented

[skeeto]

23e000b through 1e7471f introduces a newly-written nroff, enables the man app in busybox-w32, patches busybox-w32 less to support ANSI escapes (for nice man page formatting), enables man page generation of upstream projects (GCC, etc.), and adds hundreds of newly-written man pages where none yet existed. In the next release you can man COMMAND for any command in the kit.

This is strictly sections 1 and a little 7. No runtime nor system interfaces have man pages, but I'm considering the options.

[stianhoiland]

Oh f**k! I adore this!

I have wanted this so much for so long. I stopped thinking anything like this would ever happen when you said somewhere that w64devkit isn't really meant to be a development environment, just a toolchain. But that didn't stop me from using w64devkit and busybox-w32 as my only development environment for some years now. It was my introduction to actually using Unix. My IDE is my .profile. I'm in love.

In the beginning, having no real documentation for busybox-w32 was a right struggle, but now I see it as having been a blessing in disguise. Finding documentation and making it usable in the shell was something I just had to eventually figure out, and it drove me to the source specification. The documents at Open Group has become like a second home to me. For a long time I just used my browser to click my way around to what I needed to read, but after a while, and for a long time afterwards, I have used a shell function like this instead of man:

POSIX() {
  local utility=${1:-contents}
  local url="https://pubs.opengroup.org/onlinepubs/9799919799/utilities/$utility.html"
  links "$url"
}

It allowed me to type "POSIX sed" just like you would type "man sed", and it would take me to the heart and soul. I now have a thorough grasp and intuition not just of the functionality of the tools, but of what's POSIX and what's not when I see something—I know what's POSIX, I know what's busybox's particular flavor, and I know what's GNU-like. And that's really something, because it gives me the confidence to write very portable shell, and to know when I'm not and to choose which I want. Not to speak of the fantastic manual of the concepts of the shell's command language. How could something so dry be so easy to read?? As an aside, I don't know how many times I've looked up the parameter expansion table in the manual!

As you can see above, I managed to get my hands on links. It's probably the purest text browser of the bunch. I use the cosmopolitan libc build, so it's not MSYS2/Cygwin. While using links for the web at large is not something I ended up sticking with, using it for browsing the Open Group's POSIX specification is a match made in heaven. It's a purpose-built pager focused on hypertext! So I don't just read these "man" pages, I jump back and forth to linked pages, concepts, and manuals. It's wonderful.

See? I don't think I would have gotten it this good if the usual man documentation had just been there.

After a while, I found that my side-loaded MSYS2 installation has two relevant packages:

• man-db
• man-pages-posix

This allowed me to finally get actual man, which I had wanted for so long. But guess what: What I have is better! Not just in terms of navigability (while I know you can jump around in man, it's a big win to use the more modern browser paradigm), but for the current lackluster documentation of busybox it's much better to assume POSIX and discover busybox's limited extensions than to assume GNU and be disappointed almost every time. This was a realistic approach; I hadn't exactly factored in that someone would produce full documentation of the particular feature-set of busybox-w32, beyond all the --helps!

Oh, that reminds me. Before I found Open Group, other than grepping busybox-w32's repo, this was how I tried to learn: Parse busybox-w32's list of cmdlets, put them in an instantly searchable fuzzy picker, and show the chosen command's --help output:

help() {
# BUG Doesn't properly add chosen command to history.
#     Need history -a and/or history -r/-n for that.
#     Those aren't in busybox's history cmdlet :(
  local cmd=$(command help | tail -n +3 | tr -d '\t' | tr ' ' '\n' | fzy -l $(rows) -p "Command: " -q "$*")
  if [ -n "$cmd" ]
  then
  	echo "$cmd" >>"$HISTFILE" # workaround for adding to history bug, is unfortunately not loaded into memory by the shell (need history -r or something)
  	eval "$cmd --help"
  fi
}

(Eventually I found a workaround for the history. I had to write my own little C utility that uses Windows' sendinput() function to put the selected command on the prompt through synthesized keyboard input, for me to then press Enter.)

Anyway, back to Open Group's POSIX specification. Recently, I went ahead and downloaded the specification, and did as I always do: Put it in the lovely minimalistic fuzzy picker fzy:

POSIX() {
  local path="$HOME/Downloads/susv5/susv5-html/utilities"
  [ -f "$path/$1.html" ] && {
    # links is cosmo, so need cosmo path -> remove "C:"
    links "${path#*:}"/$1.html
    return 0
  }
  local choice=$(find "$path" -type f -name '*.html' | sed 's,.*/,,; s,\.[^.]*$,,' | fzy -f -q "$1")
  [ -z "$choice" ] && return 1
  # links is cosmo, so need cosmo path -> remove "C:"
  links "${path#*:}/$choice.html"
  return 0
}

Instant, full list of all POSIX utilities, fuzzy searchable—or just give the name at the command line and skip the list—takes me right into a colored, hyperlinked document. I have one of those for all of libc as well.

Anyway. That was my journey to documentation bliss. It started very bleak, but boy did it turn out well.

I'm very excited for what you've done here. I'll be pouring over your documentation and learning how I can use it well, and probably integrate it into my already existing tricks. So happy about this; well done!

[skeeto]

I'm glad you like it, Stian!

this was how I tried to learn

I've had a similar couple of functions in my own .profile for jumping into local documentation:
https://github.com/skeeto/dotfiles/blob/a67dfb0a/w64devkit.profile#L47-L64

Recently, I went ahead and downloaded the specification

I didn't realize there was a download. This is now in the README.md's recommend offline documentation (7f8bfe4), though I just realized I got the commit message wrong.

[stianhoiland]

Oh yeah, I remember coming across your lookup functions. I used similar ones that open the (GUI) browser before discovering the Open Group specifications:

win32ref() {
  if [ $# -eq 0 ]
  then
    open "https://learn.microsoft.com/en-us/windows/win32/api/"
  else
    local query=$(printf '%s\n' "$@" | sed 's/ /%20/g')
    open "https://duckduckgo.com/lite/?q=\\$query+site:https://learn.microsoft.com/en-us/windows/win32/api/"
  fi
}

cref() {
  if [ $# -eq 0 ]
  then
    open "https://en.cppreference.com/c.html"
  else
    local query=$(printf '%s\n' "$@" | sed 's/ /%20/g')
    open "https://duckduckgo.com/lite/?q=\\$query+site:https://en.cppreference.com/c/"
  fi
}

I have also ran ctags -xu --languages=C,C++ --kinds-c=+px --recurse | awk '{print $4":"$3": "$1}' >./.tags in $W64DEVKIT_HOME and have a "win32" function which feeds that ~30mb tags file into fzy and jumps to the file and line in my text editor upon selection. It's incredible to have over 600,000 symbols fuzzy searchable with instant results.

... I just realized I got the commit message wrong.

Too bad about the typo. I also want to reiterate that the Open Group specification doesn't just include the shell manual and shell utilities manuals, but also man pages for the whole of libc. You just change the utilities part of the URL to functions:

libc() {
  local function=${1:-contents}
  local url="https://pubs.opengroup.org/onlinepubs/9799919799/functions/$function.html"
  links "$url"
}

(This is the old version. My new version uses the local download and fzy like shown in my original comment.)

Maybe this is something you can include in your man set in the future. Then again, you're not much of a libc person, are you :)

[Peter0x44]

Personally, I haven't read a manpage in years. Certainly today my preference would be to go to some AI first...

I am a fan of tldr pages though. I think it's cool. https://tldr.sh.
Maybe we could include some way to have those.

[skeeto]

That's increasingly true for me now that my primary interface with computers is plain English. Though one of my goals with the kit is still a great "offline" experience, which includes developing software the old fashioned way.

[stianhoiland]

skeeto, I realized today part of why I'm so excited about this.

I'm rather anti-AI, and I thought we had lost you a couple months ago, but after perusing your new sshd and winctl today (and your skeeto-style skill from a couple weeks ago), well... Would you be proud to know that I'm coming around to it from seeing what you are producing with LLMs?

If I understand correctly, your new tool sshd (C++) started out written by just you (~4000 loc), and then you added Claude to the mix for fixups and improvements. And then, another tool winctl (C++) made with Claude (~2000 loc). These tools are so clear to read! It's a far cry from vibe coded slop. They are wonderfully readable, deconstructed, comprehensible, and comprehensive. And I must say, I'm also coming around to your C++ style, which I never thought I would; Your fundamental and restrained idioms look so good on the page.

But even more than all of that, it was really this thing you did with producing for-humans documentation. That really did a number on me, and I now realize why—because I realize why I hate AI coding.

What you have done is instead of creating massive black boxes of vast and incomprehensible hyper-conceptualized burden, encumbrance, and obligation only manageable by doubling and tripling and quadrupling down on dependency on outsourced decision and thinking, is you have boiled it all down and made a complex beast simpler. It's the diametric opposite of what I see LLMs being used for, and this has actually blown my mind—sorry for having been so dumb.

This feels so empowering and enlightening; you have turned the tide against complexity and unbounded, cancerous growth.

I don't intend to single out for criticism, but Peter's response here perfectly encapsulates my issue (nothing personal against you Peter! I'm using your reply as a representation of something worse than your actual reply): Rejection upon seeing complexity fitted and simplified for human skulls; agency rejected for continued dependency. Why not just continue to use AI to navigate ever-growing complexity, and not have to stop growing the complexity since we can just keep using AI? Don't distill, don't grasp, don't own.

Well, in this one weird swoop of producing these man pages you've shown and convinced me that it doesn't have to be like that. Bravo!

N.B. All of this is dependent on the quality of the documentation, which I haven't started reading yet because I wanted to write this out first. And since I'm now done with that, Imma jump right into it!

[Peter0x44]

Models today write very good code. I understand being skeptical, but it's such a huge productivity improvement and it's really a lot of fun. It's like having a programming genie with infinite wishes.

I would highly recommend trying a coding agent if you haven't.

Don't distill, don't grasp, don't own.

You can ask models questions, and they will give you answers knowing precisely the context of your goals, and tell you what APIs you need to use to achieve them, etc. The comprehension (or lack thereof) is a choice. You keep as much control as you want, and give away whatever control you never desired.

[Peter0x44]

In my opinion, the ux of manpages always sucked. I find the prose hard to read at times, often you're searching through them only for a single flag or function and skipping a lot of irrelevant parts, the code examples in them are insufficient, etc.

I don't think there's no value in them, just they aren't my preference now. A great tedium I can eliminate.

[skeeto]

started out written by just you

Not quite, those commits are AI except the "Makefile cleanup," just not marked as such because I used OpenCode. Sorry, I didn't think anyone would be examining the history so carefully, so I didn't bother to make it clear. It began as idle speculation about allowing AI to drive tests on my old Windows XP laptop, instead of me doing it manually and reporting the results. I have unmetered access to a fast DeepSeek v4.1 Flash instance, which are free tokens for trying such ideas, especially outside of peak hours. So I gave it a pile of RFCs and asked it to write a bare minimum SSH server from scratch supporting just one crypto suite, make it passwordless, etc., and pointed it at my other projects as style examples.

This model is not frontier, maybe somewhere around Opus 4.5, plus OpenCode is a mediocre coding harness. It's free tokens but the rig requires handholding and scrutiny (much like Claude Code in late 2025, early 2026). It fumbled around with the narrow API for no reason, requiring steering. But I was impressed enough with the results to build on it. It was at the limits of what DeepSeek was going to accomplish, plus I didn't want to continue handholding, so I handed the project off to Opus 5.5 in Claude Desktop, an incredible model in an incredible harness. It cleaned up and took it to the finish line with little steering from me.

What's particularly neat is that DeepSeek's work was enough to bootstrap, and Claude did the rest of the work in Windows XP through the initial SSH server, then later through its improved server it started itself on another port. No handholding indeed. The winctl part was mostly invented by Claude while building the new tugz GUI in w64devkit on XP. That screenshot was taken by Claude running the proto-winctl. Seeing this new tool in action, I asked Claude to integrate it with the sshd project, and so we got winctl, which is already paying off in other projects. Harnesses let AIs keep memories so that they can remember things between sessions. On my MacBook, Claude knows about this XP laptop running sshd in its memory, and regularly runs tests there, including for w64devkit. So the kit's getting more XP testing than ever. Claude isn't lazy like me, and doesn't skip testing.

made a complex beast simpler

I don't know if it's simpler, probably not, but I can comfortably and confidently manage significantly more (but not unlimited!) complexity now. It may not be obvious to anyone following along, but here's a neat fact. Every single byte in w64devkit is built from source, and we have Quilt patch trees under src/, so everything in the kit can be arbitrarily manipulated. src/README.md has some basic instructions for using Quilt, mainly for AIs, and I keep a source/ with all the source tarballs (docker build -t source --target source .; docker run --rm source tar c source | tar x). Any time I notice an issue or friction anywhere in the kit, I can start an AI session, describe my problem in plain English, and fully tested (now including XP!) patches magically appear to fix it. I don't have to identify which source tarball, and sometimes it involves more than one at a time. I never imagined I'd have something like this in my lifetime.

But when the upstream package updates the patches need updating/fixing, right? That's already solved, too! Managed complexity.

Like Peter was saying, frontier models are at least 99 percentile coders in terms of code quality, but also orders of magnitude faster. Lots of people online crank about AI hallucinations or terrible AI code, but these opinions were likely formed years ago, now woefully out of date. Or sometimes such opinions are based on some far-from-frontier model they could run on their own computer. Or if they lack any personal experience, they're based on seeing people use these tools poorly. Speaking of the latter, using AI effectively is a skill in itself. I've been improving at it all year. It's easy for me (and I imagine for Peter, too) to underestimate how much prior, pre-AI experience goes into prompts to get good results.