14 ms·
Man pages are great, man readers are the problem
- amelius 2y agoCan't we just convert all man pages to a modern format like HTML, and never look back?
- happosai 2y agoWell I read man pages Via debians web server precisely because they are easier to read in html. https://manpages.debian.org/bookworm/manpages-dev/syslog.3.en.html https://manpages.debian.org/bookworm/manpages-dev/syslog.3.e... Bit I don't think html would be a good source format.
- oneshtein 2y agoTry HTML version: man --html=firefox man
- Cthulhu_ 2y agoTriggered by your "modern format" comment, if my sleuthing is correct, the mdoc format was first introduced with "4.4BSD" from 1995, with a major update in the early 2000s', whereas HTML was first conceptualized in the 80's with a first major release in the early 90's; mdoc IS the modern format. Granted, it may not be the ideal format for documentation, but I'd argue neither is HTML - too much cruft for reading in a terminal and not very ergonomic to type out. I'd argue markdown or something like that would be a better fit, it's got support for the formatting and linking needed, most developers are familiar enough with it, you don't actually need to parse or render it to be able to read it, etc.
- amelius 2y agoFrom the mdoc manpage: > Many aspects of the basic syntax of the mdoc language are based on the roff(7) language So, I wouldn't say that mdoc is the modern format here ...
- pavon 2y agoAnd the basic syntax of HTML is based on SGML which was standardized in 1986, and which in turn was based on GML and COCOA from the 1960's.
- Lammy 2y agoRelevant: Compiled HTML Help (1997) https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help
- mplanchard 2y agoEmacs does a nice job of this, I think
- Zambyte 2y agoEmacs also highlights how underrated info pages are. Truly a hidden gem.
- hirvi74 2y agoI truly appreciate when tools come with everything one needs to know about how to use them. I think it helps foster a real sense of sustainability.
- goku12 2y agoThat is in line with the Free Software and GNU philosophy. It isn't just about making the source available to you. Rather, they expect that you - the user - will tinker around and modify it substantially to suit your needs. So they include practically everything needed to achieve that - including full documentation, developer tools, code introspection capabilities and sometimes even entire textbooks (The bundled elisp book is actually an introductory textbook on programming). The other GNU software all follow a similar strategy - be it Guix, Shepherd, Guile, Poke,... It's so pleasant to work with them. Too bad this approach didn't catch on.
- nemoniac 2y agoSee woman-mode in Emacs https://www.gnu.org/software/emacs/manual/html_mono/woman.html https://www.gnu.org/software/emacs/manual/html_mono/woman.ht...
- perlgeek 2y agoEasiest solution: convert to HTML, view in browser. If that's not an option for you: the good old `info` document reader supports links and jumping. Somehow I never quite got the grasp of it though (probably because I didn't spent enough time with it to make it worth finding out how it works).
- tasn 2y agoHard disagree. Markdown is the way to go. I've been using Linux for a couple of decades at this point, and I've use man pages quite a bit over the years. Though even though man pages are not foreign to me, I think they are no longer the right solution to the problem. First of all, we are all used to reading documents on the web (or in a code editor) nowadays, so having a completely different interface is not great. At some point 10 years ago or so I mostly stopped using the `man` command and just googled for man pages so that I can have the interface I'm used to. Additionally, developers are very much used to markdown, and most other docs are written in markdown (maybe some RST, but probably mostly markdown) so this is not great for the person writing the docs either. So man pages are inferior for both the producers and the consumers of documentation.
- Spivak 2y agoIs there some issue with writing your documentation in markdown and pandoc-ing it to the roff format? It's what I do for all my personal man pages and it works fine.
- __mharrison__ 2y agoIs there some issue with pandoc-ing man files to the HTML format? (It's not what I do, I use man from the terminal, but I understand after teaching thousands that terminal mastery is not common.)
- bregma 2y agoYes. Markdown is semantics-free. The man macro set in roff is semantic in nature. There is no bijection. If you're writing semantic-free man pages you're already doing it wrong.
- lupusreal 2y agoWhat most manuals on the web get wrong is not offering a single-page version, so you're forced to use clumsy search engines (on-site or third party) to search through the document. With manpages, the whole manual is usually in one document. Some big programs split it, usually for the worse.
- sjmulder 2y agoIt's a shame so many web versions of man pages are typeset with monospace fonts and barely any formatting. The mandoc-powered OpenBSD online man pages are great though: https://man.openbsd.org/acme-client https://man.openbsd.org/acme-client Still I also really like being able to read man pages in the terminal. Getting a bit familiar with less helps to make it convenient. I mostly use the search features (/ and ?) and half page scrolling (d an u).
- cassepipe 2y agoI should add that it supports j/k for scrolling line by line
- lupusreal 2y agoMan pages are nice to read but a pain in the ass to write (unless you're using modern tools that convert markdown/etc to the manpage, which honestly, you should be doing.)
- shadowgovt 2y ago... at which point, one does wonder why we use man at all instead of markdown.
- lupusreal 2y agoConventions matter, manpages get indexed so you can access them easily with man readers. With raw markdown docs I have to go searching for the documentation myself.
- shadowgovt 2y agoTrue, but I don't think the gap on indexing Markdown docs is very large. In fact... man already supports two parsable languages for the pages themselves. It could, hypothetically, support three.
- Jenk 2y agoI page man (and many other things) through bat[0] which improves my experience. [0]: https://github.com/sharkdp/bat https://github.com/sharkdp/bat
- vages 2y agoI use batman from bat-extras[0]. It may very well be the best named command line utility I know. [0]: https://github.com/eth-p/bat-extras https://github.com/eth-p/bat-extras
- kstrauser 2y agoWhat do you prefer about that? I already use bat for syntax highlighting but haven't used it as a pager. Edit: Oh! That's pretty. Details are at https://github.com/sharkdp/bat?tab=readme-ov-file#man https://github.com/sharkdp/bat?tab=readme-ov-file#man
- WhyNotHugo 2y agoThis approach discards all mark-up, which bat tries to re-build with some heuristics. It works for the basic case, but not beyond that.Subsections get mangled (see sway-ipc as an example). Links disappear completely of course, since they don't even reach bat.
- DadBase 2y agoExactly. The problem isn’t the man pages, it’s that folks stopped reading them with a highlighter and a cup of day-old coffee. That’s how you retain flags.
- hirvi74 2y agoIf one wants to retain flags, then why not redirect the output a man page to a text file and using an editor to make highlights?
- DadBase 2y agoTried that once, opened the file in vi, blinked, and somehow mailed it to my dentist. Highlighter never did that.
- fred69 2y agoSuccess! Coffee through nose achieved. Printouts, usually many of them, are the original "overlapping windows".
- DadBase 2y agoExactly. I used to stack printouts on the floor in layers. Top one was active, bottom one was swap. If you walked too fast past my cube, you'd trigger a context switch.
- cassepipe 2y agoAs a vimmer I was glad to discover that `less` supports j/k scrolling, search with / + n/N, gg and G. A neat trick is : export MANPAGER="less --incsearch" which mimicks the behaviour of `:set incsearch` in vim and allows you no quickly move around It really increased the usefulness of man pages by a lot for me. `info` has a vim mode but it's more obscure to me how to use it properly Any other useful tricks ? Edit: s/man/less
- blueflow 2y agoWhat you are referring to is not done by `man`, but by `less`. The pager that `man` uses is configurable.
- cassepipe 2y agoI stand corrected
- yoyohello13 2y agoNeovim supports use as a manpager: export MANPAGER="nvim +Man!" You get all the vim movement/search and highlighting.
- cassepipe 2y agoEven better, thank you for the tip
- blueflow 2y agoI disagree. I have been writing man pages for a while, and mastering the language is hard. The documentation for both mdoc and mandb format is not covering the whole language, and the only remaining reference for roff itself seems to be the book by Brian Kernigham. mdoc and mandb are like a macro set on top of roff. Just this week i considered proposing to $distro to convert all manpages to markdown as part of the build process, and then use a markdown renderer on the shipped system to display them. This would allow the distro to stop shipping *roff per default. Markdown profits from the much larger amount of tooling. There are a ton of WYSIWYG editors that would allow non-technical users to write such documentation. I imagine we would all profit if creating manual pages was that easy. On the other side, Markdown is even less formalized. Its like 15 different dialects from different programs that differ in their feature sets and parsing rules. I do not believe things like "How do i quote an asterisk or underscore so it is rendered verbatim" can be portably achieved in Markdown.
- packetlost 2y agoscdoc makes writing man pages a lot more pleasant: https://git.sr.ht/~sircmpwn/scdoc https://git.sr.ht/~sircmpwn/scdoc
- blueflow 2y agoUntil i use it "wrong" and Drew does the Drew thing with me, like he did with the hyprland guy. No thanks.
- packetlost 2y agoI'm not a fan of Drew's political grandstanding (or views, in some cases) but scdoc is good and packaged in many distros. There's no foundation for him to abuse with it, so it's safe.
- pkal 2y agoThe IRC bouncer Soju uses scdoc and this has been personally annoying, as I refuse to install it just to build semantically less expressive documentation than when using the very well documented (https://mandoc.bsd.lv/man/mdoc.7.html https://mandoc.bsd.lv/man/mdoc.7.html) mdoc format. I asked the maintainer if they were interested in a contribution to translate it, and they just dismissed it out of the box.
- kccqzy 2y agoOn macOS you can format the man pages into a PostScript which can be distilled into a PDF by Preview and then opened there. PDFs do support links for cross references. On Linux you can do the same except you will probably need to manually install ghostscript for the distillation and evince or something similar to view it. This should not surprise anyone because roff is originally designed to be a typesetting tool and the man pages are naturally printable as a nicely formatted document.
- frou_dh 2y agohttps://kapeli.com/dash https://kapeli.com/dash for MacOS supports man pages just like any of its many other documentation sources. Simply type `man:foo`. Absolute hall of fame app IMO.
- tengwar2 2y agoPostScript: this is how I solve the biggest problem I see. I don't care about linking to other pages. I don't care about reflowing. I care very much that if you use man in the terminal, the output is really hard to read other than for short man pages. man bash, for instance, is something you could reasonably want to read, but it's about 5000 lines long and in the terminal it's hard to see the organisational structure. Reformatting as Postscript shows the pages they were meant to be. I started as a Sun admin, and we used to have paper manuals, properly typeset - and that's what you get when you use Postscript as the output. For Unix/Linux users - investigate "man -t". However - MacOS doesn't support reading Postscript now. It used to, but the feature was removed from Preview. At the risk of teaching multiple grandmothers to suck eggs, I use this script: manps () { if [ -z "$1" ] then echo usage: $FUNCNAME topic echo This will open a PostScript formatted version of the man page for \'topic\'. else man -t $1 | ps2pdf - | open -f -a /System/Applications/Preview.app fi } where ps2pdf comes from Homebrew.
- wpm 2y agoPreview can no longer directly open .ps files. For shorter man pages, I use the Terminal apps "Man Page" profile which you can get to by right clicking the command name, and selecting "View man page". Then, scroll to the bottom to render the entire thing, and Command+P > Save to PDF. For long shit, parts will get truncated (overfilling the scrollback? I have no clue), so I have to export the ps with man and convert to PDF with ps2pdf. This puts everything in a basic Times New Roman font and I hate it. Much preferred when I could directly open the output on the Mac.
- jordemort 2y agoI like pinfo for this (although it is primarily intended for viewing GNU Info pages, it can also display man pages): https://github.com/baszoetekouw/pinfo https://github.com/baszoetekouw/pinfo Using it feels a lot like lynx. It recognizes cross-references between pages and allows you to navigate through them, as the author of this post requests.
- 77pt77 2y agoHas also been around for several decades
- kevin_thibedeau 2y agoThis is how I get a better man: alias man='pinfo -m'
- krick 2y agoHonestly, no. They are not great, and it's getting silly to pretend they are. If they were, we wouldn't have stuff like tldr, cheat, bropages, and a good half of StackOverflow wouldn't exist as well, let alone LLM tools to translate your verbal request to half-broken ffmpeg command. Man readers suck, man pages suck too, man markup language sucks, the contents of a typical manpage suck.
- shadowgovt 2y agoFundamentally, the problem is that manpages are a framework (and not actually a bad one, if everyone where to adhere to it and populate every section), but writing good documentation is an art and not a well-taught one.
- teddyh 2y ago> writing good documentation is an art and not a well-taught one. Some recommendations here: <https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...>
- sgarland 2y agoWe have those because people do not know other options exist, or know, and lack the patience to read. By and large, people don't read docs, full stop. This is why you get entire stack traces being dumped into Slack, or error messages that clearly state the problem.
- _7acn 2y agoI prefer Markdown :(
- kazinator 2y agoI have a man page reader which remembers the position you were in the last time you read the same man page. There is nice syntax highlighting. Also, you can jump to other man pages, because it's just using Vim. In Vim, you can use K to open a man page for the word under the cursor. You can prefix that command with a section number. Something could be hacked to scrape that from the parentheses after the word. https://www.kylheku.com/cgit/mnpgr/about/ https://www.kylheku.com/cgit/mnpgr/about/
- tomxor 2y ago> In Vim, you can use K to open a man page for the word under the cursor Holy crap! TIL, and I've been using vim for a decade.
- kazinator 2y agoI remapped K to :grep for the word under the cursor instead. The way I did it, though, is such that if I give it the numeric prefix, it will do the man lookup in that section. :nmap K "_y:execute count ? ( ":!man " . count . " " . expand("<cword>") ) : ( ":grep \\<" . expand("<cword>") . "\\>")<CR> I have it mapped to do :grep in visual mode also, without the fallback on man. :vmap K "zy:execute ":grep " . getreg("z")<CR> Maybe newer Vim has a solution for "grep word under cursor"; it's such an obvious use case. I'm trained on K though.
- tomxor 2y ago> I'm trained on K though I hear you, have an hard to overcome ctrl-d muscle memory from back in my sublime-text days. Which unfortunately conflicts a little with vim's default ctrl-d in some modes. But for the most part I was surprised how much muscle memory I could re-wire when I forced myself. I think so long as you pick one at a time, and are using it for a solid chunk of time, i.e while you are working, then it doesn't take long, ~1 week maybe until it's 90% instinct. I think I probably need to finally shake ctrl-d, maybe today is the day.
- 2y ago
- saagarjha 2y agoMan reader here. I largely agree, I’m not very good at reading documentation.
- neuroelectron 2y agoGnu and its associated tech is basically shit. Its arcane, awkward, and sometimes self-defeating aspects is only matched by its ugly naming. Stallman’s obsession with purity over pragmatism has kept GNU projects stagnant. I don't think it's the terminal interface that is a problem. The entire smell is unapproachable and just plain weird for real-world users and devs. Look at thus coreutils guide: https://www.gnu.org/software/coreutils/#mailinglists https://www.gnu.org/software/coreutils/#mailinglists This is for general help. Mailing lists. Can you think of a less productive way to manage this type of information? Sending an email to the void and siloing it in a specific reader? No HTML allowed? Yes, "man" pages are annoying to use and not helpful but that's been true for decades. Have you tried apropos? Does git really need to be so difficult? I understand creating a barrier to entry but does that even work? Has it been effective in increasing the quality of Linux tooling? Is Linux even a good ecosystem? When you see modern projects like systemd, what do you think?
- deleted 2y ago[deleted]
- shadowgovt 2y agoI think you're conflating a few pieces of the ecosystem. Linux (and GNU/Linux, and POSIX, and the tools that run on and through them) have the same great strength and great weakness: they aren't owned by anyone. To a first approximation, the only thing that gives them consistency is some loci of discourse and consensus built up around some charismatic leaders (Torvalds, Stallman). But the end result is that nobody's actually in charge of making all this stuff work together "all of the time or we don't ship," which means... It all kind of works, most of the time, with some weird corner cases that make a person dig deep into some historical interactions to fix it (TIL that manpages aren't even all in the same language, or that `man` does more that pop a file open and dump it raw to the terminal). ... but on the flip side, there's no artificial barrier to entry. If you want to get started, you can download a distro onto a machine willing to accept some media that will overwrite its boot rules and get started. And that's extremely powerful. The Linux ecosystem is awful and weird and gross and arbitrary and broken... And beautiful. And it's not going away anytime soon because it's free (beer and usually speech). The alternatives can't replace it because they generally lack the incentives to be as open and fast as the incumbent ecosystem; they either aren't free (beer or speech), so already constrain their domain to people willing to pay... Or they are too different (even if different in a better way), and therefore don't interoperate with the software that's already there and have a labor shortage (having an ecosystem that mostly works most of the time creates a positive feedback loop on improving it that is missing in the attempts to burn it down and replace it). (Side-note on git: while I concur that git out of the box doesn't make it obvious the right way to use it... In fact, there is no one right way, that's the thing about git... I've used four version control systems in my day, and git's the only one I've ever used where there was a way to do what I wanted, every time. The flexibility of its abstraction makes it tricky to delve into but powerful).
- NoSalt 2y agoI would also suggest that man pages need examples. Oftentimes, what is required, and how it is required, is not very clear, and examples would go a long way towards helping people more. Granted, some man pages do have examples, but not near enough do.
- seri4l 2y agoI agree. In case you haven't heard of it already https://tldr.sh https://tldr.sh is pretty good for this.
- criddell 2y agoIs there a local AI that could provide a more modern interface to the information buried in man pages? Sometimes I don't even know where to start and that's why I end up in Google or on StackOverflow. I'd like to be able to type "hey man, how do I show all the bootable partitions on my drive?"
- pjmlp 2y agoThere are tons of X Windows readers for man pages, none of them referred on the article, maybe that is already the first problem.
- gnuser 2y agoGnu info for anything gnu, then man pages, then tools like tldr
- teddyh 2y ago• Info¹ • Gnome Devhelp² • Zeal³ • Local RFC archive⁴ dumps (by Debian⁵) • Man pages 1. https://www.gnu.org/software/emacs/manual/html_node/info/ https://www.gnu.org/software/emacs/manual/html_node/info/ 2. https://wiki.gnome.org/Apps/Devhelp https://wiki.gnome.org/Apps/Devhelp 3. https://zealdocs.org/ https://zealdocs.org/ 4. https://www.rfc-editor.org/ https://www.rfc-editor.org/ 5. https://tracker.debian.org/pkg/doc-rfc https://tracker.debian.org/pkg/doc-rfc
- ksynwa 2y agoMy dream feature in man page readers is to somehow go to the description of a specific flag. Maybe it already exists and I don't know about it. But as of now I resort to regex hacks like searching for `^\s+-p` or `, -p` to find where the flag is described.
- shadowgovt 2y agoAs far as I can tell, this is the missing feature: flags definitions are extremely semantically meaningful to humans and not even `mdoc` has expliict semantics for them (the closest you can get is that the pattern `.It Fl A` almost always means "the -A flag's definition", especially if it's in the DESCRIPTION section, but that's not a hard-and-fast rule). And of course, even if your pager isn't `less`, by the time the content has been fed through `man` itself it's been crunched into a terminal representation, not a semantic representation. You'd have to `man -w whatever` to get the raw file and parse it yourself (and handle whether it's mdoc or man format, etc.). The regex you have keyed that matches to "What these flag definitions usually look like on the terminal" is almost certainly the saddle-point solution between using the tooling as it is and burning it to the ground to build something better.
- ryandrake 2y agoI'd love to be able to type: man ffmpeg "-ss" And have it jump right to the -ss option so I can see the expected format. For me the 99+% use case of man is to look up parameters of a command line or parameters of a programming function call. It's shocking that the UX for what I presume is the single most used use case is so broken.
- deleted 2y ago[deleted]
- sudahtigabulan 2y agoDoes searching with /-ss not do this well enough? For options, the first hit often is the description. When it's not, filtering with & can give you an idea how much further it is, so you can repeat the search with n. It's not an exact, "semantic" jump, but I find it good enough.
- shadowgovt 2y agoInteresting! I never thought about the issue being the reader treating it as just strings and making that an ill-fit for the problem domain. My bugbear with man is that the only way to find a particular flag is via string search, so if I want to find out what "-c" does I'm going to bounce off of every hyphenated word starting with "c" in the file. Turns out `mdoc` makes it extremely easy to find those flags (they're all `.It Fl <whatever>` macros), but by the time it gets all the way to `less` that detail has been squeezed right out of the file. Emacs manpage display is like 90% of the way there but lacks a function to "find flag in file;" I should look into how hard that would be to hack in.
- bentley 2y agoOn systems that use the mandoc implementation of the man(1) command, these semantics are preserved and accessible from within less(1). See my other comment: https://news.ycombinator.com/item?id=43634894 https://news.ycombinator.com/item?id=43634894
- SuperNinKenDo 2y agoI's be inclined to agree, but having tried to use Emacs man and woman modes for viewing manpages, I wonder. There's always something broken.
- tomxor 2y agoExpanding on pjmlp's comment [0] buried in this thread: export MANPAGER="nvim +Man!" Using Vim's built in ft-man-plugin [1] as the default man pager seems to go pretty far towards resolving what the author is complaining about. Links work, and it respects the indentation when soft wrapping lines. It isn't doing full reflow or regenerating the page, but it maintains legibility while soft wrapping, and messing up indentation is my main annoyance with less... You can improve less by chopping lines -S by default, but then you have horizontal scrolling so neither is great. [0] In Vim, you can use K to open a man page for the word under the cursor [1] https://neovim.io/doc/user/filetype.html#ft-man-plugin https://neovim.io/doc/user/filetype.html#ft-man-plugin
- impalallama 2y agothe crawlers are working hard today because I got lead here just by searching for a better man page on kagi I liked the idea of using nvim but i rewrote it with bash function for easier argument handling nman () { if [ $# -ne 1 ]; then echo "Usage: nman <command>" return 1 fi command nvim "+hide Man $1" }
- dannyfritz07 2y agoThank you for this. This is actually quite marvelous. Here is what I'm using for fish: if type -q neovim set -gx MANPAGER "nvim +Man!" # abbr --add man --set-cursor "nvim \"+hide Man %\"" end I can finally retire fisher and decors/fish-colored-man.
- loodish 2y agoThe vanilla vim version is MANPAGER="vim +MANPAGER --not-a-term -" Documentation can be found via :help manpager.vim
- jasonjmcghee 2y agoI found reading man pages with syntax highlighting to help just enough to make them readable for me. You need bat installed- and then you can set the manpager in your rc. (But as an example it's doing) MANPAGER="sh -c 'col -b | bat -p -l man'" man tmux
- taeric 2y agoGetting used to browsing info pages in Emacs is something that is rather nice. You can do similar with man pages, there. Often times, it will let you jump directly to the source code of includes and such, if you want to take a peak at the actual code. To that end, I fully agree with the idea. The richness of existing man pages is far nicer than many people seem to realize. I do find a bit of dismay at the folks that want to ditch some of that richness and move to markdown or similar. That lets you layout some things fine, I think. I am 100% convinced that as you try to get all of the linking and general semantics of the existing solution done, you will find that you have added a lot of "schema" expectations to markdown that isn't there by default. And then you will start to build "markdown schema" tools to check that what you have fits some standards. And then... Seriously, just look at a lot of the data that moved to JSON from XML. I saw they are trying to add namespaces to JSON in some projects. Truly terrifying to see people slowly and poorly add the features of the more complicated thing they avoided the first time around.
- m463 2y agoI think markdown is actually too heavy. It is really a layer over HTML, which seems to mean you have to have a browser.
- taeric 2y agoI think the larger problem with markdown is that it is not semantic at all? Yes, the "break glass to drop into html" is a problem. I'm assuming folks would try to disallow inline html, though?
- arcfour 2y agoIt's honestly hilarious to watch people poorly hack everything XML had back on top of JSON, but this time without any sort of standard.
- taeric 2y agoHilarious, but largely in a scary and sad way.
- HankB99 2y agoWill I be struck down or downvoted into oblivion if I mention man2html? Definitely not light weight since it also installs Apache, but I do like to view man pages in the browser. I think 'python3 -m http.server' could be substituted for the server and perform well enough for a single user system. It's unfortunate that Markdown isn't better standardized so it could be extended to better meet the needs for man pages. (Do we need a new standard to rule them all? Yes, I'm thinking of the XKCD comic.)
- foxyv 2y agoMarkdown, Markdown Extended, GLFM, Mediawiki Markup, Asciidoc, reStructuredText (RST), Pandoc, Mundimark, Djot, Creole, Textile, BBCode, Dendron, Pendown. I bet at this point if you came up with a new completely independent standard it would probably match one of the ones already created. We mostly just have to pick one.
- graemep 2y agoI find KDE Help centre makes a good man page reader: pleasant to read, searchable, and references to other man pages are links (I do not think references within the page a links though).
- Pxtl 2y agoImho, fundamentally man pages fail because they're generally a bunch of descriptive front-matter and then an exhaustive list of parameters, when 99% of time users want to do some of the most common actions with this tool and so the first things shown should be explaining how to do common workflows with examples.
- jmclnx 2y agoOpenBSD man pages are great. NetBSD and FreeBSD are a close second. Linux man pages stink. Many Linux man pages points to info(1). Nothing is worse than info. I would rather search facebook for help on Linux than use info :)
- teddyh 2y agoIf you have ever used the terminal-based standalone “info” program, please try to forget all about it. Use Emacs to read Info documentation, and preferably use a graphical Emacs instead of a terminal-based one; Info documentation occasionally has images. Also, the enforced structure of man pages does not encourage good documentation: <https://news.ycombinator.com/item?id=6655417 https://news.ycombinator.com/item?id=6655417>
- yyyk 2y agoIf you're thinking of man readers, do consider the mandoc (previously mdocml) project. By treating the page semantically (rather like a macro language), it can achieve better results (pretty HTML output, even markdown output!). https://mandoc.bsd.lv/man/mandoc.1.html https://mandoc.bsd.lv/man/mandoc.1.html
- mmphosis 2y agoI've mostly abandoned man pages. The manual is contained within the program: program --help
- bentley 2y agoI hate --help. First, I hate having to run the program. If I wanted to refresh myself on the shutdown command, running “shutdown --help” would make me extremely nervous! There have been times where I’ve only had source code and wanted to read the documentation before taking the time to compile it or install dependencies or whatever. With a manpage I can just pipe it through mandoc. Sometimes --help output is short, sometimes it’s 150 lines long and scrolls off my screen. So I hit up, end, |less, and I get nothing, because in some programs it goes to stderr instead of stdout. So I hit up, end, ^W, 2>&1 |less. Ugh. And --help is not even close to a universal convention. In some programs --help will open HTML documentation in a browser (really!?). Often programs don’t print help at all, instead printing a generic “bad flag” error. Some will create a file named --help without asking! Some programs don’t use long options and relegate it to -h, or -?. Manpages are a much more universal convention, thanks to Debian’s policy that all packaged programs have manuals. I don’t even use Debian, but I encounter manuals attributed to them all the time. I do my part by writing manpages for my own software and sometimes contributing new manpages to programs I encounter that don’t have one.
- mmphosis 2y agoI agree. I just ran "shutdown -h" and it turned off my computer. I need to look into creating man pages again. Command 'mandoc' not found, but can be installed with: apt install mandoc A universal convention would be nice. That whole stdout vs stderr business. openbsd-cut -badoption | less I didn't even consider -?. And -h can mean --how-many-different-things: Host, --human-readable, --poweroff (as I just discovered), open HTML documentation in a browser (just wow), and maybe Help, maybe not enough help, maybe too much help, maybe...
- sgarland 2y agoFor small programs with limited flags, I like (and write them this way) having `--help` simply list the expected syntax, and a brief description of the short and long flags. If I need a pager to read it, it's too long for `--help`.
- m463 2y agoemacs hyperlinks man pages quite well.
- willjp 2y agoFun fact - you already have them. The gnu project made ‘info’ pages decades ago to solve exactly this problem. It never caught on outside of the gnu project though, sadly.
- aboardRat4 2y agoXFree86 has been shipping xman, a GUI viewer for manpages, since 1984 or about that time.