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.

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.

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.

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 think people tried to convert man pages by redefining the macros and then let nroff produce the output.

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.

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

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

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

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

  alias man='pinfo -m'

Holy crap! TIL, and I've been using vim for a decade.

[0]: https://github.com/eth-p/bat-extras

Edit: Oh! That's pretty. Details are at https://github.com/sharkdp/bat?tab=readme-ov-file#man

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.

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.

No affiliation, just an avid user.

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

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.

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.

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.

  $ man --html man

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

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

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  
    }

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.

Also, the enforced structure of man pages does not encourage good documentation: <https://news.ycombinator.com/item?id=6655417>

    export MANPAGER="nvim +Man!"

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.

https://manpages.debian.org/bookworm/manpages-dev/syslog.3.e...

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

  man --html=firefox man

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.

• 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

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.

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

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