when do you usually use the man page for a complex command line tool to answer a question you have?
Uncategorized
272
Posts
207
Posters
0
Views
-
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")
@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
-
@b0rk The broadening of the programming environment has also taken its toll. The manual covers C and shell programming, but a lot of work today is in different language environments that have their own documentation, some good and some bad. Even in the standard utilities, something like awk or sed is very difficult to learn from the reference manual. Perl at least was always good at making manual pages for every installed package, but they depend on authors to get the information structure down.
@wollman this all makes a lot of sense to me, personally I've never been a C programmer and so the classic "unix reference manual" style always feels like a bit of an alien life form and like it came from a different time.
-
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")
@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."
-
@karabaic I've never used openbsd but I'm so curious about the openbsd man page culture because of how people talk about it
do you know if there's anywhere that I can read about the documentation philosophy or about how people relate to it?
@b0rk The FAQ on posting to the openbsd.misc group is a good place to start. after reading man intro. I'd then check the contribution standards on the project.
It's considered incomplete to try to check in code with user-visible functionality that's not explained in the accompanying man page so it can be tested with by reading that page.
-
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")
@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.
-
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")@b0rk The man page is closer to the source of information, rather than some random website one found via web search. Plus, given differences between OSs/distro releases, how do you know what you get from a web search matches up with what you have actually installed?
-
@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
@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? 🤔
-
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")I always go to --help first to get an idea of what my options are or to scope my question better, then I can search for examples using whatever option vs searching "how to X" if that makes sense
-
@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
-
@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
-
@b0rk The broadening of the programming environment has also taken its toll. The manual covers C and shell programming, but a lot of work today is in different language environments that have their own documentation, some good and some bad. Even in the standard utilities, something like awk or sed is very difficult to learn from the reference manual. Perl at least was always good at making manual pages for every installed package, but they depend on authors to get the information structure down.
@b0rk tcl, as I recall, shipped with a whole new "section" of manual pages for its intrinsics that you could opt to install, but I don't know anyone who actually wanted that. That was in the days when any system worth its salt shipped with at least nroff and -man macros — some systems made that a separately licensed add-on, forcing third-party software distributors to ship preformatted documentation. That was probably the start of the downfall, because it opened up the options for doc authoring.
-
when do you usually use the man page for a complex command line tool to answer a question you have? (like git, openssl, rsync, curl, etc)
(edit: no need to say "i use --help then man")
@b0rk I think most man pages have a lot of detail and are great resources. But.....While they go into great detail they lack the concept of basic use. Take the tar command. Great compression utility with lots of options. Most people just want to decompress files. How do you do that? I had to search on google for the answer. Yes the proper syntax was buried in the man page in different parts. I think a basic command example at the begining of the man page about what most will be using the utility for would help.
-
when do you usually use the man page for a complex command line tool to answer a question you have? (like git, openssl, rsync, curl, etc)
(edit: no need to say "i use --help then man")
@b0rk I typically start with `-h/--help` flags to see any obvious answer. Then move to man pages after the fact. If I can't find the answer there then move up to a web search.
-
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")
@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/manand even$HOME/.local/share/manthe 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? 🤔
-
@b0rk I typically use -h or --help first, then the man page if necessary.
@bortzmeyer @b0rk same. and then web search if the man page is unhelpful. i think part of it is trying to avoid a context switch from the terminal?
-
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")@b0rk personally, it's usually the case that I've used the tool before, I know that it does the thing I want, I just don't remember the invocation details.
So, it's faster to grep the manpage for keywords than launch a web browser.
-
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")
@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. -
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")@b0rk I want to love man pages. I do find them great as detailed reference material, although sometimes a bit impenetrable.
But I don’t (usually) find they are pedagogically well structured. Eg, in general they do not provide lots of examples of uses, from simple basics to more involved use cases. In general they don’t have split in to “basic use and overview” and “advanced use and detail”.
I might be holding it wrong and / or not very bright, though.
-
when do you usually use the man page for a complex command line tool to answer a question you have? (like git, openssl, rsync, curl, etc)
(edit: no need to say "i use --help then man")
@b0rk There are still cases where a system has no internet access (regardless of whether for technical, organizational, or legal reasons). Every tool should have reasonably comprehensive offline help/documentation; it could be --help (if it's complete), it could be man, it could be info, or even documentation in plain .txt — it doesn't matter, as long as I still have access to the documentation on a system cut off from the network.
Every non-trivial tool failing to do this is just deficient.
Additionally, websites (contrary to popular belief) aren't eternal. They disappear—and the more niche the tool, the more likely it is to happen. And when they go, the documentation vanishes with them.
-
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")@b0rk staying in the terminal feels important. Not breaking flow. Checking --help is part of the same task, tabbing out to search is having to start a new task to get the previous one done.
(subjectively, to me, etc.)
Feed RSS
Gli ultimi otto messaggi ricevuti dalla Federazione
-
Deposito di smarino di Susa: Bussoleno si attivi per Vis e Via
@anarchia
Egregio Sig. Sindaco del Comune di Bussoleno In riferimento al progetto citato rileviamo con estrema preoccupazione che in corso di definizione degli interventi ritenuti indispensabili per la realizzazione delle opere previste nella così detta “piana di Susa” si è proceduto,...Vedi l'articolo
-
@Voline ah, it was intentional, sorry 8-) I think this is the first time I've seen this made on purpose to avoid a preview, the usual strategy is to add an image or something, so that the link remains clickable. Sure would be nice if the preview card could be controlled 8-(
-
re: https:
Yeah, sometimes I don't want a preview card to appear in a post.
-
@mcc «this 1 could easily be a 5 with the right incentive, hint hint»
-
Bigstonk Bureger
-
@stefano This is an absolutely legitimate use case for CW. I find myself both hungry and hating you at the same time.
Cheers! 😎
-
may I have a simple burger PLEASE, sir
-
@mcc how much are they willing to pay
