Hacker News Reader

Comment by smarks | Hacker News Reader

I'm curious as to how many people care about nroff/troff style man pages. I work in the group that delivers the Java JDK, and for many years we delivered nroff/troff man pages for the commands such as java, javac, javap, etc.

Some time ago because of "Corporate Documentation Standards" the sources were converted into some XML-based markup, from which nroff/troff markup was produced -- not entirely successfully. More recently because of "Revised Corporate Documentation Standards" the XML sources were converted into yet another format, and the team responsible has given up maintaining the tool that converted that format into nroff/troff. So the plan now is to deliver straight HTML, with the rationale being "nobody looks at man pages anymore."

As an old UNIX hack I opposed this, to no avail.

Are man pages really irrelevant?

View on HN

Manpages still matter for Linux systems. Not necessarily for GUI-only tools, but any command-line tool should have a manpage. They remain the most convenient and consistent form of documentation for command-line tools, with the possible exception of --help.

If you need to know which command-line option to use for a particular behavior, consider the relative amount of time needed to find out via a browser and search engine, versus installed documentation, versus a manpage. And if the search engine comes close, half the time it does so by finding the relevant manpage (or excerpting the relevant manpage snippet).

The troff markup language remains terribly baroque, and in truth it hardly matters except as "the thing that existing manpages all use so the man tool handles it". Nothing but inertia and existing infrastructure keeps that format necessary, but learning the small subset of it needed for manpages doesn't take long, especially if you copy an existing manpage as a starting point.

Groff knows how to produce HTML from a manpage, and the result can help if you want to provide documentation that works on other platforms.

The conventions of manpages matter far more than the markup details. If "man sometool" popped up with troff-formatted documentation that didn't have the expected sections and section order, it wouldn't have anywhere near the same value.

I look at at least one man page probably every day. And I'd be really surprised if this wasn't the case for anyone who works on the command line.

I look at man pages all the time.

On the other hand, I avoid Java as much as possible, so I might not be the best test market.

I don't use the terminal for viewing man pages. I often reach one via a web search. Plenty of websites host them. I think traditional unix man pages are extremely useful as documentation for two reasons.

The most important thing is how detailed they are. Man pages contain everything one needs to know for unix programming. If applicable, they specify standards conformance and document behavior that standards leave undefined or implementation-defined. They document system calls, functions, files, programs... Everything a capable user could ever want information on. They provide detailed technical information.

Another nice thing about man pages is how they don't require an internet connection. They're usually installed alongside the packages they document. This is useful if the system is disconnected from the internet.

I don't think the man command itself is essential to unix man pages. I think the detailed documentation they provide are the most important thing. One could install documentation in HTML format and use a browser for viewing -- wouldn't that be just as good?

In fact, git has an option¹ for doing just that. Passing --web instructs git to display the manual page in HTML format in the user's browser of choice. It could be a graphical web browser or a text browser such as Lynx.

¹ https://git-scm.com/docs/git-help#git-help---web

The Debian packaging guidelines requires a man page for every command line program. Any missing manual page is regarded as a bug.

https://www.debian.org/doc/debian-policy/ch-docs.html#s12.1

Of course they are. Any significantly tasked sysadmin probably uses them on a daily basis and as *nix systems programmer I'll find myself using manpage reference when I jump into something that I haven't used for awhile.

Many situations they are much more convenient and accessible than online or html docs.

sure, if you ship broken man pages, people will stop using them.

Reply on news.ycombinator.com