Mastodawn

i'm very curious about everyone who says "I'd look there first", if I want to figure out how to do something new I think I'll usually google how to do it rather than look at the man page, and then maybe later look at the man page to look up the details

(I've gotten enough of these answers:
- "I like that man pages don't require changing context"
- "with the man page I know I have the right version of the docs")

mkl1987 Feb 20

Julia Evans

i think part of the reason I'm feeling interested in man pages right now even though I rarely use them is that search has gotten so much worse, it's frustrating, and it makes it feel more appealing to have trustworthy sources with clear explanations

also it just occurred to me that the one time I wrote a command line tool (https://rbspy.github.io/) I didn't write a man page for it, I made a documentation website instead. I don't remember even considering writing a man page, probably because I rarely use man pages

(not looking to argue about whether command line tools "should" have man pages or not, just reflecting about how maybe I personally would prefer a good docs website over a man page. Also please no "webpages require internet")

Introduction - rbspy: A Sampling CPU Profiler for Ruby

aburka 🫣Feb 20

@b0rk there's also the aspect that man pages are stored on my system when the tool is installed, whereas websites inevitably disappear over time and can be temporarily inaccessible for any number of reasons

aburka 🫣Feb 20

@b0rk do we need a --help that starts a local web server hosting a doc page which is way easier to read and navigate than a man page? 🤔

@aburka that's what fish does! Well it just opens the HTML file in the browser, no need to start a local web server for those docs

Enno Rehling Feb 20

@b0rk @aburka this should honestly be the default for non-man docs: open the local HTML documentation from /usr/share if it's been installed there, or on the web if it hasn't. I still prefer to have man pages, but agree they are a hassle to create.

Viraptor Feb 24

@aburka
Ideally I'd like something progressive, like an interactive --help that shows and allows search over the normal --help content, but starts pulling in man sections or full documentation when the previous levels don't contain matches. Transparently tiered docs 😀
@b0rk

anarcat Feb 20

@b0rk i've begun to feel more strongly that i need manual pages for everything, and good ones at that. the problem is manpages are stupidly hard to write, and duplicate a lot of stuff from --help. i always solve this by converting from markdown, and generally failing at DRY

Jonathan Hartley Feb 20

@b0rk I suppose that adding a man page requires extra hurdles of not just creating the man page itself, but packaging your tool such that the man page gets installed along with it. Now you have to make a .deb and and .apt and whatever else, instead of just saying "download this script or executable and run it."

@tartley yea I'm not sure if anyone's ever packaged rbspy for Debian because (at least at the time) packaging Rust projects for Debian was hard or maybe impossible

Tony Finch Feb 20

@tartley @b0rk an idea i copied from git is to make -h print the short summary and --help brings up the man page

i have embedded the man page in the script or binary so it doesn’t have to be installed separately (tho it only works with the man command if the man page is installed)

dgelessus Feb 20

@fanf @tartley @b0rk TIL that Git's -h and --help do different things. What an unfortunate UI though :( It goes completely against the principle of long options and the established behavior of -h/--help in every other CLI tool, and even the git(1) man page claims that -h and --help are identical??

Very useful to know though. Previously, I used tricks like "git remote blarg" to get the short help, and was a little confused/surprised that there was no better way to see the short help text.

dgelessus Feb 20

@fanf @tartley @b0rk Oh, it's actually even worse! `git remote -h` shows the short help, but `git -h remote` outputs the man page.

`git remote --help`, `git --help remote`, and `git help remote` also all show the man page. So the specific spelling `git <command> -h` seems to be a special case. This is extremely unhelpful behavior for an option that's meant to be used when you don't know how to use a program... :(

Emily_S Feb 20

@b0rk I've written a few command line tools over the years that launch a web broswer to display stuff.

I'll keep the idea of having a docs subcommand spawn a local web server and broswer to view guides, could be useful.

gibwar Feb 20

@b0rk I've written man pages before when building internal tools. It was fun learning the ROFF language or whatever. Part of my reluctance to do it with general tools is the requirement to install them as satellite files which is a bit of a pain when it comes to single binary downloads.

I know there's alternate locations you can put them, like /usr/local/man and even $HOME/.local/share/man the directory structure after that is also a bit of a pain. 😅 And then there's the need to remember to clean them up after the fact if you no longer use the tool.

It'd be neat if some of these apps had the ability to drop the files and a cleanup step to remove them so they could still be single binary. Another thought would be extending man to see if the the requested page is available normally, and if not, see if there's a binary in the path that matches that name? Maybe the man page could be embedded in another section so it didn't have to be executed to generate help? 🤔

ednl 🇪🇺Feb 20

@b0rk I very much agree with your consideration: search is worse & frustrating, look for trustworthy sources. For older people (like me..) it's probably easier or more natural to switch back to reading the manual instead of searching as the first option.
I understand how the doc website was more logical to you. But I think a second reason to prefer a man page or readme or whatever, is that websites are so ethereal. They require maintenance that's often not content related, so they get abandoned.

@ednl yeah, I think the answer to "will there always be a way to get free and reliable static site for open source projects?" is not obvious

When I made that site it felt like github pages would be there forever, and maybe it still will, but I feel less certain of what the future of that looks like than I did.

Tristan Colgate-McFarlane Feb 20

@b0rk one advantage with a man page packaged with the tool is the versioning. The man page should hopefully be the correct version for hte installed tool, avoiding some potential confusion.
I do tend to use man pages for old C libraries if I need docs too. Interestingly I don't do that for Go packages (I either use the local src doc strings that my editor jumps to, or I'll use the pkg.go.dev site).
(obviously there are no man pages for go pkgs, but I rarely use go doc directly)

Jan Schaumann Feb 20

@b0rk FWIW, I first write the man page, then the code. Helps me clarify what the user wants, how I will interact with the tool. I then generate the README from the man page.

#Digital ⚓️ #Vagabond 🦈Feb 20

@jschauma @b0rk famously README driven development! Although I guess, manpage driven development! :D

Fred Feb 20

@b0rk getting good documentation is the important bit. One good thing about mandoc is you can render your man page as html and serve it from you website.

Martin Feb 20

@b0rk I almost always google my way to a website manual when I need to know how a tool works. Or I settle for `command --help`. Maybe I should add man into the rotation

Henrik Pauli Feb 20

@b0rk The point of having a man page (or as you edited the original post: a --help) is that it's self-contained and, hopefully, true to the actual thing you're trying to run. The website requires an internet connection and it might be about a newer version than you have (did your distro or you forget to upgrade the tool?) or older (did the author forget to update the documentation?) and while a site is often a better UX (graphical browsers and whatnot), those are issues to be considered.

Yes, sometimes you end up looking at a BSD flavoured man page when you're running Linux and you don't even know there is such a thing as BSD so you don't know to look for a mismatch.

cate Feb 20

@b0rk note: Because Debian requires man pages, I notice that lot of the are written by debian developers, so I assume also a lot of developers don’t use man pages. (note also that writing man pages was very difficult, not just content, but technically: complex non standardized language, various tools, and I still not sure there is a guide on conventions)

Chris Siebenmann Feb 20

@b0rk For me I think it's a composite of four things:
* old pre-good-search habits of reading manpages first, which also gives me lots of practice at navigating them.
* I often only want some specific piece of information (eg 'what switch is used for ...') that I can find with a search of the manpage in less
* Internet search has gotten untrustworthy and bad.
* Sometimes I want to see the authoritative 'what the program says' instead of people describing it.

Norman Wilson Feb 20

@cks @b0rk All the above, plus that my habits were formed back in the ancient days (when PDP-11s and VAXes roamed the earth) when manual entries were mostly clear and concise and programs mosly simple and straightforward and could be described clearly and concisely.

Yes, I'm a grumpy old fart.

Kerrick Long (code)Feb 20

@b0rk I've written --help output, but I've never known how to write a man page.

Tony Mottaz Feb 21

@b0rk something I like about the fish shell is that the `help` command opens the bundled documentation site in your browser. It’s all local and pinned to the actual version you’re running. I would 100% take something like that for any CLI tool

Peter Krefting Feb 21

@b0rk Back when I was a Debian developer, I wrote man pages for programs I packaged, since everything should have one (it's part of rhe packaging guidelines).

Some of the Debian man pages have made their way back upstream (not any of mine, that I am aware of).

I started using computers when they were not always online, so I grew up with local documentation as the primary source.

TheConstructor (he/him)Feb 21

@b0rk I regularly look at e.g. https://linux.die.net/man/ https://www.man7.org/linux/man-pages/ or similar sites for man pages when not on linux. The man-format seems to render well as html. I did try info some times, but preferred the single-document approach of man as I could more easily search in it. I do prefer to have an option to have the documentation in the shell, as I can use e.g. screen to copy things into the command I am preparing. Scenario here would be ssh into a *nix environment from Android or Windows, where you rarely have that documentation locally. Of course you may offer HTML-pages additionaly

Linux man pages

John Maxwell Feb 20

@b0rk I date from the days when man pages were a novelty.

If it doesn't have a man page, it isn't finished.

Master Squinter Feb 20

@b0rk
I tend to look for examples close to what I want to do, or tutorials. I would love if man pages were more consistent in giving clear examples for common use cases. This is much easier to parse quickly than detailed explanations.

excited for the mastodon rise Feb 20

@b0rk One thing, and I don't know that this is solveable or maybe it was supposed to be solved by info pages but those were hard to memorize how to use, is learning the capabilities of a tool like...up front and at the top.

It's so hard to find the ingredients I need to concoct the correct incantation from man pages, even when I've done the thing with the tool before.

And sometimes you find things that SEEM like what you need but aren't.

Minkiu Feb 20

@b0rk I agree with the sentiment, and I think that's why I installed tldr.sh again recently 🥲 granted that's far less in depth that what is provided by the man pages, but examples are concise.

Jerome (He/Him)Feb 20

@minkiu @b0rk omg this would’ve saved my mind when I was tinkering with tmux which has the worse man page I’ve ever seen.

@b0rk I have a lingering guilt about not going to man pages first, but often a blog post has been better crafted than the friendly manual. Not all manuals but enough to encourage an antipattern in search first.

I totally agree with your motivation to address/revaluate that.

@RyanParsley to be clear for me i'm mostly interested in figuring out if the man pages can become _better_ so that using them is actually a good experience, not accepting a bad experience

@b0rk a general statement of when official docs feel not super helpful is when they clearly articulate what a tool does without managing to express why/when kinds of context.

A good blog post about a tool tells a story that docs don't tend to.

Why does `man stow` mention perl or Carnegie mellon's depo program? That man page is pretty good all around but does have stuff to skim over that doesn't feel like it's there in service of the user.

@b0rk when you say better, do you mean content or format? Like jq man page is pretty stellar on the content side.

@RyanParsley either!

(it's a little hard for me to think about jq because I've completely given up on learning the jq language, but I don't think that has anything to do with the quality of the documentation)

@b0rk are you already familiar with https://tldr.sh/. I don't have it in my workflow, but seems like a neat idea to complement man pages.

Even if you have no interest in using it, perhaps it's existence and what's working there could be useful data.

tldr pages

Simplified and community-driven man pages

@RyanParsley yeah! i think 20 people have told me about it today haha, I don't use it either but people tell me all the time that they like it, I think it's an interesting project

Mattias Wadman Feb 20

@b0rk @RyanParsley any idea what are the main pain points make it hard to learn? "everything is a generator" and how arguments work are two of them it seems

@wader not sure, maybe the idea of learning a specialized domain specific language just doesn't feel worth it. Like I've never learned the awk language either

Mattias Wadman Feb 20

@b0rk that makes sense, and same for me about awk, maybe because jq fills that gap for most of my needs. but it you ever need to do lots of adhoc query and transform of semi-structured data i can recommend to learn jq!

@wader been trying out fx recently and I think it might work bette for mer, we'll see https://cheat.sh/

cheat.sh/:firstpage

Mattias Wadman Feb 20

@b0rk 👍 good to hear, only used it briefly. happy to answer jq questions if you ever venture into it again

@wader thanks so much!

@b0rk the man page for just is basically a less pretty help command :)

I suspect if people discover too many in a row like that and stop running that command.

r-hold Feb 20

@b0rk i remember this: when i learned about man and started using it, the stuff i wanted to know usually was on page 5 (quick reference / parameters). But i always forget that so it felt frustrating and abandoned them.

Instead I use --help command options. I only go to man when i want to learn the full and long version. But sometimes I do.

Sandzwerg Feb 20

@b0rk usually I'd first look at --help, then web search, then man page. If I know it's a certain option and I just don't remember the name or how to use it it might be --help, man page then web search.

Jonas Schäfer Feb 20

@b0rk I'm the kind of person who enjoyed reading man pages for leisure.

I read through the entirety of the rsync man page to compose my own favourite rsync invocation once.

The only tools where I resort to web search are shells, because their man pages are really hard to navigate (finding documentation for `read` in the bash man page is ... a nightmare).

Web search is often imprecise and as you note, has gotten so much worse that I am glad I never fully relied on it.

Damien Sorresso Feb 20

@b0rk I gave up on groff so long ago that I forgot to try using an LLM to create a man page from HeaderDoc and Markdown. I'll have to give that a shot sometime.

Zoé Cassiopée ✨Feb 20

@b0rk The only reason why I'd use a search engine is to find where the manual is (e.g. what's the URL of the official Podman documentation again?). Top search results are just articles generated from obsolete Stack Overflow answers anyway. Otherwise I hope the man pages and --help give me the basics I need, and point me to more extensive documentation options if needed.

I picked "I'd look there first".

doragasu Feb 20

@b0rk I use them a lot when doing C programming to lookout function prototypes and documentation. When using vim, just place the cursor on the function name, hit SHIFT+K (or 2, SHIFT+K or 3, SHIFT+K to go to specific manpage sections) and you are instantly reading the page, really handy.

Melroy van den Berg Feb 20

@b0rk Ai is also not helping, if you are using llm? A good man page or help output can correct AIs.

Justin 😸Feb 20

@b0rk I feel this. The part about search is the main point. keyword/regex search in man has always been a bit awkward even with helpers, google used to be great at bringing up the official site or man pages (which, even if it was for a diferent distro, at least help with context).

usually I try `-h` or `--help` first, then search, then man.

davecb 🇨🇦Feb 20

@b0rk One of the best features of the older man pages was a keyword-in-context index. See https://en.wikipedia.org/wiki/Key_Word_in_Context for an example.

If I thought of a word, I could see where it was used in man pages, and ONLY in man pages. Low noise, high granularity.

I'm tempted to make one as Appendix B of a small reference book I'm writing. I bet I can use my concordance file and grep for each of the words, reporting chapter instead of page in on-line formats.

Key Word in Context - Wikipedia