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.
You're used to reading documents on the web. I am used to reading them on paper, in the terminal using man (strictly, troff and less), in the web browser and in a split or tab in vim (also using troff). I wish people would stop this "we" business where they purport to speak for everyone.
Man pages are superior because they don't give you the opportunity to add all the other stupid markup, animations, css etc people put in HTML documentation. The key thing is that they're consistent. Always in the same format.
Man pages don't have to be in troff. And as you illustrated, nothing stops you from generating web pages from them.
> I wish people would stop this "we" business where they purport to speak for everyone.
That has become a strong signal regarding the (lack of) quality in any argument. Anyone using this cheap rhetoric trick gets an immediate penalty in my "how seriously should I take this person?" book.
> I wish people would stop this "we" business where they purport to speak for everyone.
Saying that we are all used to consuming content in a web browser is hardly a controversial comment, especially when posting on HN which is accessed using a web browser. You most likely read my comment on a web browser and wrote it on a web browser.
Additionally, you said yourself the sentence before the one I quoted that you are used to reading documents on the web, so it seems like this "we" also applies to you. So I'm just baffled by both this and the sibling comment.
In full context, it was implicitly "as opposed to anywhere else".
I look at many documents every day. 90% of them are PDFs and most were Word docs before that. Pages on the web are incredibly unreliable. In the programming world random websites are more commonly used but I don't think they are actually much more reliable. A lot of online resources are just some guy's blog post. Sometimes they're great. Sometimes not.
No, I wasn't implying "as opposed to anywhere else". I spend much more time a day in the terminal than the browser (todos are in vim, knowledge in vimwiki, code in vim etc), but I realize not everyone is this way and the web is the much more common medium.
personally i hate when i have to open a web browser to view documentation. it's an absolute waste with how heavy they are and the interface sucks. troff is a nicer markup language than markdown. definitely prefer man pages over anything else.
There was a time that web-browsers were content viewers, in that time they were more efficient by far than things like PDFs.
Man pages are more efficient but difficult to print, they don't include hyperlinks to more context, or inline images to provide some kind of higher level understanding.
Web browsers became application distribution platforms, and thus; I agree with you- they're really heavy for just document viewing these days.
What 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.
Big time. I don't do that very often anymore, but it used to be how I read all documentation. There is a lot to be said for being able to flip through physical pages with a highlighter in hand.
Markdown is semantically less expressive than man's markup. man goes into details like explicitly marking up command's arguments.
You can convert man to Markdown easily using full capabilities of Markdown, but Markdown lacks semantic information to be converted back to fully-features man document.
If we had good man viewers that have consistent level of support, then man would be a better data source format.
Unfortunately, there's no way to know what features man viewers support, and AFAIK no good ways to provide graceful fallbacks. This is most broken with tables and links that have dedicated markup, but are not rendered in common setups.
> Markdown lacks semantic information to be converted back to fully-features man document.
Core Markdown, yes. Pandoc has a fenced div extension that can capture the semantic meaning.
::: Warning :::
This is a warning.
::: Danger
This is a warning within a warning.
:::
:::
Not suggesting that Markdown is the right tool, only that it has extensions to capture semantic meaning. Here are example documents produced using Markdown:
But the various man source formats aren't semantic markup of any particular use. Yeah, you can ensure that all of your arguments are typeset as italic or something, but it's not consistent because there are different source macro packages and they do different things.
If there was useful semantic markup, it'd be great, because you could imagine, for example, tools allowing you to generate commands on the user's behalf. But the man source formats are mostly, at core, typesetting for 70's typesetting machines, not intended for modern reference documentation.
mdoc(7), which is the primary macro set used on BSD systems, is a 90s language (as opposed to a 70s language) with useful semantics that support both hyperlinking and featureful search, both on the web and in the terminal.
But the biggest value of manpages to me is somewhat independent of the underlying format: its quality as documentation. BSD systems have a strong tradition of cohesive usability, including good manpages. A lot of the manpage alternatives I see advertised in Linux circles (such as tldr pages or bro pages) are of little use to me, because OpenBSD manuals are thoughtfully written, clear, concise, complete, and have useful examples. The difference is very noticeable when I try reading manpages for programs I’ve installed from packages, which are often incredibly sparse or incredibly verbose, and lack examples in both cases.
The nifty features that come from the modern language and tooling used by BSD manpages are really just symptomatic of the overall care that BSD communities put into their documentation generally. I wish it were more widespread in the free software world.
Having been using Linux for a couple of decades as well, i'd never give away manpages in the terminal.
Any time i need a quick refresher ("was it -f or -F?") i can just pause the current editor (ctrl-z) look up the manpage (man <whatever>), exit (q) and then go back (fg) to whatever i was doing.
Having a web browser is just useless annoyance in the workflow.
I find it weird that most of my younger colleagues totally do not understand job control, and generally use just a subset of shell features in their day to day development work. I would wager they also don’t value man pages. I remember the blank stares I was met with when I suggested we create a man page for an extremely complex CLI tool we maintain.
There was already an often out of date wiki page that people hated maintaining, nobody could understand why you wouldn’t just use that.
As other child comments have stated, this is entirely subjective, and many would disagree with you (myself included). I live primarily in the terminal, and the ability to seamlessly look up syntax, flags, features, etc. without ever leaving the keyboard is wonderful. Additionally, I agree with milesrout that I do not want emoji, animations, etc. in my manuals (nor my terminal). I want searchable text. I also agree with lupusreal that having a single large page, at least as an option, is ideal.
A perfect example of the two approaches is HAProxy. Here [0] is their commercial site. It's very flashy, modern web, etc. I don't necessarily hate it, but it's definitely designed to get the attention who may not necessarily know what they want, and can be sold to. In comparison, here [1] is their community site. It is extremely Web 1.0, and I love it. Everything you need, nothing you don't. Similarly, their docs [2] are [3] logically [4] split, and manage to be readable, navigable, yet information-dense. I don't need a tutorial with code snippets every few paragraphs in my docs.
> 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.
Web devs, perhaps, though I imagine there's more variety than you think. Kernel devs likely do not have the same opinion as you (though I do not wish to speak for them, as I am not a kernel dev). I've seen the same argument against the build and packaging process for Linux distros, like Debian. "Why is so much of this in Perl," "why are there so many bash scripts," etc. Because that is what the original developers wrote it in, it works well, and at this point is largely bug-free. Drastically changing something to suit the tastes of some at the risk of introducing errors is not a reasonable strategy.
I am a kernel dev and you've captured my thoughts on the matter quite well. I would very much rather stick with man, even with the deficiencies the article discusses, than use markdown and web.
It doesn't have to be either/or. You can generate a rich format to mdoc. I'm not completely convinced markdown isn't sufficient, but it doesn't have to be markdown.
Is 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.
Is 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.)
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.