Hacker News new | past | comments | ask | show | jobs | submit login

The irony is that Daniel J. Bernstein said in the late 1990s that switching to HTML is the answer. And here we are, almost a quarter of a century later: Most of the people claiming that they are reading manual pages are actually reading HTML documents with WWW browsers. (All of the people following the hyperlinks to man pages found in this very discussion are doing that, for example.)

* https://cr.yp.to/slashdoc.html

Strictly speaking it's not advocating HTML, but "browser-compatible" documents, which in fact includes DocBook XML.




And there are tools such as Debian's dwww (<https://packages.debian.org/bullseye/dwww>) which present virtually all local system information through a Web interface, also queryable through shell tools.[1] Both man and info pages (as well as numerous other document formats) are presented as Web pages, making info's distinction between man and hypertext formats largely irrelevant.

Note that this is a case of Debian's packaging conventions, standards, and requirements, as well as the wealth of available packages (including many documentation packages) being leveraged with a small additional bit of glue package to provide a fantastic utility.

As concerns man and info: I prefer manpages for their simplicity, use of ubiquitous tools and pagers (info by default relies on its own idiosyncratic viewer programme which I can never remember how to use or navigate, though you can bypass this for other tools). Info pages can offer richer documentation in more detail, in instances, though I find that generally HTML would be preferable for this. Note that both info and the WWW were invented within about five minutes of each other. Well, a few months, at any rate. Stallman really should acknowledge the clear winner here, as info's idiosyncrasies very much hurt rather than help it.

________________________________

Notes:

1. That is, in addition to man and info pages, you can point your browser at <https://localhost/dwww/> to see the content. You'll also get the /usr/share/doc/<packagename> trees, any installed manuals, auxiliary package information, and access to installed documentation such as RFCs, Linux Gazette, and other sources, if you've chosen to install those as well. Search is via swish++. Presentation can be limited to the localhost interface only (that is, only users on that system can view the docs) or opened up to specified IP ranges.


I feel the real key is having it in a separate window/terminal - I remember a TSR for Dos that would drop down a half window with command help - and you could scroll it AND still work on your command line with special modifier keys.

We do that now with a browser window open as we enter commands.


tmux and screen users would say that one can use the roff-based man system and still do that. The key is, rather, in what M. Bernstein wrote: "Much more effort has gone into web browsers than into roff readers."

And this is true. I just recently fixed a bug in a 2018-ish man command that prevented it from displaying Japanese manual pages, because it defaulted to 7-bit ASCII instead of UTF-8. Any WWW browser that couldn't have handled UTF-8 in 2018 would have been junked by most people. That sort of stuff was fixed years before for WWW browsers.

Indeed, there's been the reverse process going on. The effort that has gone into roff readers has sometimes even been actively suppressed. Did you know that your manual pages actually contain italics for emphasis and denoting certain syntactical elements, and have done pretty much all along? groff got the ability to display them, like troff originally could, long ago, as well as colour; but these abilities have been explicitly disabled in most operating systems.

We'd laugh at WWW browsers that couldn't do all of <i> and <em> and <u> and suchlike, or (of course) their CSS equivalents. But we suppress the ability of free software roff readers to reinstate what Unix text processing could likewise actually do in the 1970s.


Part of the reason the Gentoo wiki/docs are so good is that they use color and links - both totally doable in text mode consoles, but both neglected.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: