hckrnws

Hey really cool! Tcpdump co-author here. If you're interested in the origin story of the tcpdump language, bpf, and pcap, I had fun putting together a talk a number of years ago... https://www.youtube.com/watch?v=XHlqIqPvKw8

For normal, day to day use, examples in documentation is absolute gold. As a practical matter, that's how we human learn to do things. Perhaps surprisingly, even AI benefits from examples.

Children don't learn to speak a language by learning all the grammar and conjugation rules first. They learn by repeating phrases they've heard before and they generalize. Usually we learn tools the same way. We see someone else using a tool, and we do what they're doing, and generalize.

That's not to say that man pages should consist only of examples. There are times when you really do need to understand how the tool processes corner cases and really understand how it works. But I expect most of us here can relate to the experience of opening the man page for a tool and being completely baffled by a wall of unfamiliar jargon. Most of the time you just want to see how to do the most normal common functions, especially when you're learning a tool the first time.

Absolutely. manpages are useful as a reminder if you already know how the command works but can't remember what option enables foo-output, but pretty much useless for figuring out how to use the command all you get is 15 pages of options and flags in a long list. This is one thing that MSDN got right, look at, for example, the page for CreateFile, I can't link directly to the examples section but drop down to the end of https://learn.microsoft.com/en-us/windows/win32/api/fileapi/... and hit PgUp a few times (I deliberately chose an extremely complex function here, the docs for most others aren't that long).

Why stop at man pages examples, should go all the way to literate programming enabled examples with the help of CUE configs language [1].

Perhaps it's overkill for power users, but most of the users will probably find it handy for the tricky find tool and friends [2].

I think other Unix/Linux users will find the literate programming approach as more useful, intuitive and less error prone ways to complement The Linux Programming Interface book [3].

[1] Cue Does It All, but Can It Literate? (22 comments)

https://news.ycombinator.com/item?id=46588607

[2] find(1) — Linux manual page:

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

[3] The Linux Programming Interface:

https://man7.org/tlpi/

A simple Markdown to roff translator seems like an ideal project for an AI to tackle.

I’ve looked at that a bit. Roff and mandoc etc have specialized tagging that’s not easily representable in markdown. You’d wind up with a lot of boilerplate or special non-standard markup, which would undermine the point.

The LLMs are super good at doing that translation, though. They can write those formats no problem.

Docbook is a thing.

It is a thing. But hardly anyone uses it because it’s way too much of a thing.

My go-to for examples is ‘tldr’ Maybe you could add the examples there, too? Then again, if every man page had basic usage examples, maybe I wouldn’t go to ‘tldr’

It's a bit weird to see someone doing free work for the community and then ask them to do even more free work.

I also like:

  cheat() {
     curl "cht.sh/$1"
  }

[flagged]