Man pages are great, man readers are the problem | Hacker News Reader

Man pages are great, man readers are the problem

whynothugo.nl

138 pointsWhyNotHugo162 comments

I 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.

Yeah. Without even looking at google, I bet there's a "mandown" project that formalizes markdown with man extensions.

The irony of the poor state of affairs of the quality of documentation for mdoc & mandb are not lost on me.

EDIT: couldn't resist. There's at least two mandown projects.

It's such a good name that, once you thought of it, you'd almost be obligated to start writing the code.

scdoc makes writing man pages a lot more pleasant: https://git.sr.ht/~sircmpwn/scdoc

Until i use it "wrong" and Drew does the Drew thing with me, like he did with the hyprland guy. No thanks.

I'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.

The 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) 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.

Who cares how expressive it is? It hits all the core pieces of formatting you can realistically do in a terminal using syntax that is familiar to a much wider range of developers. The output is completely usable and reasonable. I'd rather use something closer to markdown than roff macro gunk that is largely irrelevant anywhere else.

adoc is fine and is more widely supported. Linux (the kernel) documentation is written in adoc, along with man pages for many projects like git:

https://github.com/git/git/blob/master/Documentation/git-rm....

I wasn't aware AsciiDoc could be used to generate man docs. I'm not a huge fan of AsciiDoc's syntax, but I can see that being preferable to other options.

Asciidoc doesn't support links in man pages. It can only link to URLs. If you check the repo which you linked, you'll see they use some perl code to actually inject links.

I've used it quite a bit. It doesn't support links to other pages nor links to other sections. Which arguably is fine, since man page readers don't render them anyway, but HTML renders also suffer because of this.

Even the most vanilla of markdown (the Daring Fireball kind) means committing to a good chunk of a Web rendering stack. You'd need some pared-down version.

I don't think Markdown is the right language to solve these problems. As you've noted, it's not standardised at all, and you'd have to pick an interpreter that everyone could agree on (and that means C).

Markdown also doesn't do semantic references. It does do plain links, you can give them a title; or you can use a default title, so perhaps you could infer the semantics from the context, maybe like:

    Use the flag [-R][] to recursively apply to all files and subdirectories.

    Please refer to [chmod(2)][] for the details.

But that feels like overloading one kind of syntax with so many different meanings. Take HTML as a counterexample, it has <link rel="...">, which fits neatly into the rest of the language.

Why do these semantics matter? Well, you can obviously render roff into HTML and browse the man pages online; also, someone ought to write a simple and smart pager that can follow these references (Emacs doesn't count as simple).

Anything that aims to replace roff should preserve its most important features, have a proper formal spec, and be easy to write a parser for - in super plain dumb C/flex/yacc.

Semantics also matter for the apropos/whatis database. Not sure how many people know about them.

I only knew `apropros` from gdb. It looks pretty neat as an alternative to googling that function i never remember the name of.

Thanks :)

RST/Sphinx solves that problem in that there is a single canonical dialect, and it's already effectively used in many very large projects, including the Linux kernel and (obviously) the Python programming language.

Another big plus in my book is that rST has a much more well defined model for extensions than Markdown.

MyST Markdown has syntax for docutils roles and directives.

Does the sphinx-build groff manpage builder also build from markdown, which sphinx also supports?

If you want to know more about nroff (which is what man calls when you want text output, I believe), then you could e.g. read https://www.nesssoftware.com/home/mwc/doc/coherent/manual/pd..., or https://www.quut.com/berlin/ms/troff.html. It's terse, like nroff itself.

I think people tried to convert man pages by redefining the macros and then let nroff produce the output.

As noted there are already HTML versions of the manpages that work without apparent issue. It makes me think about having the documentation converted to html and then have a thin script that invokes w3m on the correct file.

Then again GNU tried something similar with the info pages and it never really caught on. I think that was more due to the info program being kinda hard to use and the search facility being awkward.

man -H

> It makes me think about having the documentation converted to html and then have a thin script that invokes w3m on the correct file.

`mandoc -T html` will do this for you with functional links between man pages and links to sections inside man pages.

GNU trying with info pages was largely hampered by the fragmented UNIX world of the day? I seem to recall various UNIX controllers were far more active in standards and such than they seem to be today. Specifically, I don't think any one company had the dominance that would be needed to drive a large migration.

Not that I'm certain that company exists today. There does seem to have been more consolidation than we had back then.

I think it was more hampered by the default viewer program operating like EMACS, which if you're a regular EMACS user is great if you're not it is not terribly ergonomic. What was the command to find the next search item? Ctrl-X N?

I didn't think info was at all bad. But the boss who had responded 'uh-hu' to a demo of documentation in Linux, responded 'Wow!' to the same document converted to HTML and displayed in Mosaic. These days, I suppose that I only see info in connection with Emacs.

Sounds like your major gripe with mdoc(7) is that lack of better documentation for the format and a shortage of tools to generate it. I agree on this second item, most tools don't support adding cross-references / links.

At this point, markdown is 12 different standards, some of which even diverge on the most basic things like their treatment of newlines and how to wrap text. But even so, markdown provides mark-up for styles, with no semantic meaning. mdoc has macros to mark-up flags, optional flags, arguments, environment variables, files, etc. How to format this depends on the reader, and we can have much richer readers than we do right now. Simply converting man to markdown discards most of this information.

A new format isn't going to help solve this; what we want is better guides and tools for produce high quality mdoc pages.

I disagree as well, but on a bit different grounds.

Man pages often lack examples of the syntactical structure, and the syntax is not appropriately documented either.

You can have commands where the flag is followed by an argument, but that flag also is positional, and the position is not documented. You can't just read the man page and get a working command, there's a lot of trial and error which is naturally solved by having a section of commands in an extended form with examples. Powershell does this, and they took it, from somewhere though I'm having trouble recalling the exact name at the moment I know it wasn't an innovation on their part they just glued a bunch of things together that were used in isolation.

Getting 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.

I think markdown is actually too heavy.

It is really a layer over HTML, which seems to mean you have to have a browser.

I 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?

It's honestly hilarious to watch people poorly hack everything XML had back on top of JSON, but this time without any sort of standard.

Hilarious, but largely in a scary and sad way.

Expanding 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

the 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"
  }

Thank 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.

The vanilla vim version is

    MANPAGER="vim +MANPAGER --not-a-term -"

Documentation can be found via :help manpager.vim

It'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

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).

I should add that it supports j/k for scrolling line by line

I 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

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.

Has also been around for several decades

This is how I get a better man:

  alias man='pinfo -m'

I 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/

> 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.

I 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.

> 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.

In Vim, I use Ctrl-T to indent, and Ctrl-D to deindent (in cases where automation doesn't handle it). Ctrl-T works with the correct indentation amount which is defined by the value of "shiftwidth"; whereas the Tab key inserts a tab, or spaces to get to the next tabstop if "expandtab" is in effect.

I trained myself on Ctrl-T more than 20 years ago; some people remap the Tab key to indent.

I page man (and many other things) through bat[0] which improves my experience.

[0]: https://github.com/sharkdp/bat

I 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

What 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

This 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.

My 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.

As 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.

I'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.

Does 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.

Sometimes it works, sometimes it doesn't. Sometimes the application has options like -o and --original and --output, and they are littered throughout the man page, so if I only want -o, I'm getting dozens of false positives.

You know, I cut my teeth on AT&T SVR3. I loved reading up on the basic tools and learning their options and then putting them into everyday practice.

In those systems there were far fewer tools, far fewer options, and much simpler workflows, so honestly I didn’t need to endlessly flip through manpages to sift out hundreds of options with arcane, incompatible, unintuitive syntaxes. The few options we needed to memorize were always paired with consistent syntax and impeccable mnemonics to remember (who can forget ‘ls -l‘ or ‘rm -f‘?)

Ironically, ‘vi‘ was already quite evolved, complex, and arcane by this point, but that was completely different: it was required for us to acquire proficiency in order to code, and it was easy to build skills from basic to expert/power, and all ‘vi‘-editing commands still featured those standardized mnemonics and consistency that can only come from a proprietary single-entity codebase. Plus all possible legacy compat with ‘ed‘ which nobody used directly anymore!

So while we may today consider this a lacuna in the reader tool, it wasn’t by design, and I blame the explosion of “GNU long options” and lack of standardization, more than anything. But also ‘tar‘ and ‘ps‘ and BSD vs. the world. Eff those guys.

https://m.xkcd.com/1168/

It’s fun to compare BSD alternatives to GNU software and BSD documentation to GNU documentation. For example, OpenBSD refused to integrate GnuPG for package signing due to its complexity, instead developing its own signify(1):

https://man.openbsd.org/signify.1

https://www.gnupg.org/documentation/manuals/gnupg24/gpg.1.ht...

Oops, sorry, this is GNU software, so we need the real documentation from texinfo:

https://www.gnupg.org/documentation/manuals/gnupg/

GnuPG certainly has more features. Does that make it better software? For checking signatures (the only thing I’ve used GnuPG for in 15 years), I find the signify(1) documentation more readable and the signify(1) tool more usable.

Or how about tar(1), everyone’s favorite punching bag due to its weird options?

https://man.openbsd.org/tar.1

https://manpages.debian.org/bookworm/tar/tar.1.en.html

https://www.gnu.org/software/tar/manual/tar.html

Yikes!

I would recommend 'manly'[0] for that. It's a super convenient tool for looking up descriptions for specific flags.

No affiliation, just an avid user.

[0]: https://pypi.org/project/manly/

The `.Fl` macro identifies flags in mdoc, so what you're asking for is perfectly doable.

This feature exists, on systems that use mandoc as the default manpage formatter and viewer (such as OpenBSD).

In HTML output, definitions for flags, environment variables, and other such things are converted to hyperlinks, and hyperlinks can point directly to them. https://man.openbsd.org/ssh#D

In terminal output, this same capability is used to create a ctags file, which is supported by less(1). On OpenBSD, I can type “man ssh”, then :tD to jump to the tag named “D”.

This relies on the mdoc(7) language’s semantics, so unfortunately it won’t work for manpages using the older man(7) macros. But nearly all BSD manpages are written in mdoc(7), and a significant minority of manpages from packages.

Yes, ctags is not full hyperlinking but is is quite helpful for navigating a single man page in the terminal.

If 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

Hard 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.

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.)

Yes. 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.

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.

> Some big programs split it, usually for the worse.

For some reason ZSH provides split manpages and a concatenated manpage (zshall, iirc.) I personally just use the concatenated manpage

> What most manuals on the web get wrong is not offering a single-page version

Obligatory: https://blog.nawaz.org/posts/2025/Apr/an-appeal-to-documenta...

> Printing out the documentation

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.

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.

Someone needs to devise software and a standard for viewing documents over the internet.

> Web browsers became application distribution platforms, and thus; I agree with you- they're really heavy for just document viewing these days.

Too bad they are crap at printing. Apparently rendering on the screen and rendering an image are two completely different things.

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.

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.

For example, here’s a search for “C functions beginning with ‘str’ and with return type size_t”: https://man.openbsd.org/?query=Ft%3Dsize_t+-a+Fn~^str&apropo...

On OpenBSD you can do the same from a terminal:

$ apropos -s 3 Ft=size_t -a Nm~^str

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.

"whatis -O In [some c library function]" is a very handy one

That’s way better than my example!

> 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:

* https://impacts.to/downloads/lowres/impacts.pdf

* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...

* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

* https://gitlab.com/DaveJarvis/keenwrite-themes/-/blob/main/e...

> Hard disagree. Markdown is the way to go.

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.

[0]: https://www.haproxy.com

[1]: https://www.haproxy.org

[2]: https://docs.haproxy.org/3.1/intro.html

[3]: https://docs.haproxy.org/3.1/configuration.html

[4]: https://docs.haproxy.org/3.1/management.html

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.

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.

This is not necessary, man-db can automatically convert your man pages into HTML and show them in your preferred browser:

  $ man --html man

Basic Ubuntu 24.04 install:

    man --html man

    man: can't resolve man7/groff_man.7
    man: command exited with status 3: (cd /tmp/hman6rTowJ && /usr/libexec/man-db/zsoelim) | (cd /tmp/hman6rTowJ && /usr/libexec/man-db/manconv -f UTF-8:ISO-8859-1 -t UTF-8//IGNORE) | (cd /tmp/hman6rTowJ && preconv -e UTF-8) | (cd /tmp/hman6rTowJ && tbl) | (cd /tmp/hman6rTowJ && groff -mandoc -Thtml)

The error seems to be about the groff manpage that I didn't even ask for? Very confusing.

Which Markdown? That is the problem with Markdown.

Whatever. As long as I can view it easily in Emacs (ideally using their info tool), I'm good. :-)

Easiest 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).

Interesting! 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.

On 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

Emacs does a nice job of this, I think

Emacs also highlights how underrated info pages are. Truly a hidden gem.

I 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.

That 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.

See woman-mode in Emacs

https://www.gnu.org/software/emacs/manual/html_mono/woman.ht...

Imho, 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.

On 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.

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.

PostScript: 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.

Preview 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.

The font is Times, not Times New Roman. The original PostScript standard only mandated three font sets: Times, Helvetica, Courier.

Personally when reading long man pages (or any long documents), I greatly prefer a proportional type face over a monospace one like in the terminal. These days, people's hand-written markdown also overuses the backtick syntax to make too many things monospace. Using a proportional font just feels right to me.

I 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.

I agree. In case you haven't heard of it already https://tldr.sh is pretty good for this.

OpenBSD 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 :)

If 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>

There are tons of X Windows readers for man pages, none of them referred on the article, maybe that is already the first problem.

I 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

Man reader here. I largely agree, I’m not very good at reading documentation.

I 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).

Fun 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.

As 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

What you are referring to is not done by `man`, but by `less`. The pager that `man` uses is configurable.

I stand corrected

Neovim supports use as a manpager:

    export MANPAGER="nvim +Man!"

You get all the vim movement/search and highlighting.

Even better, thank you for the tip

Can't we just convert all man pages to a modern format like HTML, and never look back?

Well 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.e...

Bit I don't think html would be a good source format.

Try HTML version:

  man --html=firefox man

Triggered 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.

From 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 ...

And 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.

Yeah ok, but HTML won the heart of the modern user.

HTML is easy to parse and generate. I've never seen anybody attempt to claim that it's enjoyable to read or write.

Relevant: Compiled HTML Help (1997) https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help

I'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.

I've mostly abandoned man pages. The manual is contained within the program:

  program --help

I 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.

I 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...

For 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`.

XFree86 has been shipping xman, a GUI viewer for manpages, since 1984 or about that time.

I prefer Markdown :(

Man 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.)

... at which point, one does wonder why we use man at all instead of markdown.

Conventions 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.

True, 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.

emacs hyperlinks man pages quite well.

Gnu info for anything gnu, then man pages, then tools like tldr

• Info¹

• Gnome Devhelp²

• Zeal³

• Local RFC archive⁴ dumps (by Debian⁵)

• Man pages

1. https://www.gnu.org/software/emacs/manual/html_node/info/

2. https://wiki.gnome.org/Apps/Devhelp

3. https://zealdocs.org/

4. https://www.rfc-editor.org/

5. https://tracker.debian.org/pkg/doc-rfc

Exactly. 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.

If 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?

Tried that once, opened the file in vi, blinked, and somehow mailed it to my dentist. Highlighter never did that.

Success! Coffee through nose achieved.

Printouts, usually many of them, are the original "overlapping windows".

Exactly. 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.

Will 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.)

Markdown, 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.

Honestly, 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.

Fundamentally, 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.

> 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.htm...>

We 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.

Is 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?"

Gnu 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

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?

I 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).

I personally am grateful for the free base bundles. Thank you, GNU.

> Look at thus coreutils guide: 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?

Wait until you find out how Linux PRs are developed and accepted.

Reply on news.ycombinator.com