[unimpressive]

I'd rather see a system that replaces man entirely. Maybe with a modern markup language like XML, Markdown, or HTML.

A system that makes documentation less painful by letting me connect to a server to downnload man pages potentially written by people other than the project maintainers. I'm not sure how you would match man pages to programs, but it would be preferable to the current situation where unless the project maintainers don't see docs as an afterthought, the on-line doc system gives you sub-par information.

You could also add radical concepts like hyperlinks. And you could fix the broken linear paging metaphor. Which doesn't work for documentation more than about a page or two long.

As for backwards compatibility. Symlink man to the new system. Done.

[thristian]

Somebody already came up with a system to replace man entirely. It was designed to use a tried-and-trusted document format, it added hyperlinks, interactive navigation, and a unified hierarchy for all documentation in the system.

It's called GNU TeXInfo, and it's terrible. Even with a third-party Info viewer like pinfo, it's still clunky and awkward and difficult to find things. The bash manpage may be a thousand pages long, but I can search for "BUILTIN" or "REDIRECTION" and pretty quickly find what I'm looking for, without much fuss.

[unimpressive]

The problem with texinfo has nothing to do with it's document format, hyperlinks, interactive navigation, or a unified hierarchy. It does however have everything to do with the info reader being totally unusable. From the texinfo documentation (Read through the info reader.):

" This all probably seems insultingly simple so far, but _please don't_ start skimming. Things will get complicated soon enough! Also, please do not try a new command until you are told it is time to. You could make Info skip past an important warning that was coming up."

It's a bloody text reader. It shouldn't ever get "complicated". For that matter, it has the most obnoxious scrolling ever. It's hard to tell where one page starts and the other ends. (Contrast with: Less.) I shouldn't have to memorize keyboard shortcuts to navigate. (At least not in a system that wants to be used and supported by anyone who isn't the most hardcore of users.)

On top of that, part of the reason I can't use the texinfo reader is because it very often doesn't have the "info" I want. And just takes me to the top node or whatever. So let me go ahead and append to "As for backwards compatibility". The system should also be able to take and render man pages as though you were using man, because expecting 30 years of projects to all move to any new system is ridiculous. And supporting man page format really shouldn't be that hard.

The closest thing to what I'm thinking of is something like the links web browser. Which still falls short. And with all that in mind, it's not like I expect anyone else to do it. Thats probably like the first rule of project ideas. Unless you do it, it won't be done the way you want it to be.

[unimpressive]

For what it's worth I thought about what I said and noticed some flaws. (Which I would correct through an edit but enough time has elapsed so that I can no longer do so.)

You mentioned pinfo, which you say still sucks. That probably IS a fault of the document format. (Which can be outputted to HTML, XML, DVI, etc, but is not itself a widely used text format.) After all, it was designed for a broken reader. And if you design something for something that's already ill designed, the end result is usually something as bad as or worse than the original article.

You also mentioned search. The thing about search is that even if the bash documentation was split into multiple parts, it's still a text file. So you could have your hypothetical man+ reader do something like:

  cat /wherever/your/docs_are_stored/* | grep '-A 100' '-e search_term'

And then let you go through the matches to find what you want.

[thristian]

For what it's worth, the "pinfo" tool I mentioned works like the links web browser, searches texinfo documentation and falls back to manpages if it can't find relevant docs. It's definitely the Least Bad way to browse info documents by a significant margin... and yet, I keep using man.

[unimpressive]

Thats worth quite a bit. As a result of this I am going to have to seriously reconsider my position. I'll try using pinfo for a while (Since it DOES use a curses library.) and see if it's what I had in mind. If so, and it does suck, I'll drop large portions of the idea. The main change I'm interested in is the "networked man pages" concept anyway.

[nwmcsween]

Troff is domain specific and even worse than info, man has one good thing going for it - it's a simple text stream.

[thristian]

*roff is domain-specific in that it's a typesetting system, like TeX but much, much simpler. It has output drivers for rendering to PostScript, ASCII output with overstrike (as emulated by, say, less(1)), and in modern versions, even UTF-8 and HTML. I have production code at $EMPLOYER, for instance, that uses it to generate properly-formatted tables in plain-text emails (easier than building HTML and rendering it with elinks, since groff is already installed).

[TerminalPrgrmr]

md2man's input is already Markdown and its Roff output already supports hyperlinks: https://github.com/sunaku/md2man/blob/master/test/md2man/rof...