Man pages are great, man readers are the problem

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.

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.

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.

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.

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.

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.

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.

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.

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.

I think markdown is actually too heavy.

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

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.

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

The vanilla vim version is

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

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

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

This is how I get a better man:

  alias man='pinfo -m'

Has also been around for several decades

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

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.

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

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

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.

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.

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.

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.

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.

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

  $ man --html man

> 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

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

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