As a tangent, I remain impressed by manpage's staying power. GNU tried to move ahead with Info, a tree-based doc format and viewer, but that never really seems to have taken off, possibly due to UI issues (I'm always confused about how to use it) It's a pity: have you tried searching for something in, say, Bash's manpage? It's just a flattened version of its doc, and you're completely flooded with search results.
I suppose manpages are another example of "worse is better". They are extremely simple to use, which is what you want when you're frustrated and looking for that *$#& option to 'find'. And yet, the troff/groff formatters used by manpages can be pretty sophisticated (Kernighan mentioned in an interview [1] he still used it to write books, eschewing to complexity of Latex) and can produce a variety of formats, such as HTML or PostScript. Why don't distributions make more use of this? I miss the days where you could "man foo" in KDE's quick launch bar and get a nicely HTML formatted version in Konqueror.
Info was a brilliant idea for its time, and it synergizes brilliantly with Emacs for those of us who use that editor.
For those who don't, it's a UX nightmare, because the standalone info viewer uses a specific, relatively ill-surfaced subset of Emacs conventions for its navigation commands. No one who doesn't use Emacs can be expected to know any of these. Even those of us who do use Emacs often don't know any of these. It took me more than half a decade of daily Emacs use to discover them.
And even leaving that aside, Texinfo is fundamentally broken in a really disappointing way: the source includes almost no semantic information whatsoever - imagine HTML with no whitespace squashing and no tags except <br> and <a>. Worse, there is no consistency whatsoever among different authors on what structural conventions to use. It's therefore somewhere between very difficult and nigh impossible to implement anything like this rather nice colorization of manual pages. There are a couple of Emacs packages which try to do that, but while they do the best they can, that best isn't very good - and, of course, they're only useful if you use Emacs.
Honestly, it's a really frustrating situation. Texinfo manuals, especially those from the GNU project, tend to be much more detailed and complete on average than manual pages, which makes them an excellent reference for cases where the aide-memoire style of a man page doesn't convey the context you need. But the info system is practically impossible to use unless you're very familiar with Emacs, and even when you are, it's still almost impossible to make info any more useful than plain text would be.
Given the age of Texinfo - older than three-fifths of the developers who answered Stack Overflow's 2016 survey! - it's not terribly surprising that it was born with flaws like these. But after thirty years, it is somewhat surprising that those flaws still exist.
For those who don't, it's a UX nightmare, because the standalone info viewer uses a specific, relatively ill-surfaced subset of Emacs conventions for its navigation commands. No one who doesn't use Emacs can be expected to know any of these. Even those of us who do use Emacs often don't know any of these. It took me more than half a decade of daily Emacs use to discover them.
I hope future generations of user interaction designers pay heed to this.
If you're going into the GNU info system to begin with, you're trying to get help, because you don't know something. Chances are, you may not know much about the system at all. So navigating your help system should be very, very easy.
Because I'm trying to figure out some other program, and I don't want to spend 15 minutes trying to learn the help system first.
A WordStar-like on-screen navigation help for GNU info would have helped me immensely through the years. Yes, it would have wasted valuable screen real estate, so the advanced users would eventually have created a command-line alias to disable it. Guys like me that used GNU info once a year (if that) would have had a much easier time.
Even better: say, you've opened info for something and are lost in it, and try info info, what you get is a list of all the available info pages, preceded by (on my machine):
This is the Info main menu (aka directory node).
A few useful Info commands:
'q' quits;
'?' lists all Info commands;
'h' starts the Info tutorial;
'mTexinfo RET' visits the Texinfo manual, etc.
You'd think that's helpful, but...
hitting '?' brings a "Regexp search backward" prompt...
hitting 'h' brings... (oh irony) the info man page (but it's displayed by info, not man), and the man page has absolutely no information about how this thing works. Only command line arguments.
There appears to exist throughout the "standalone" Info viewer an assumption that you have Emacs globally installed. (I can't imagine why.) If you don't, you're stuck with whatever info documentation your distro packager and software developers provide, which usually is both not much and not good.
Anyway, here's throwanem's handy-dandy cheat sheet for Info navigation:
m - Select a currently displayed menu item, with partial entry and tab completion
p, n - Move to the previous and next sibling nodes at this level of the tree
u - Move to the parent of the currently displayed node
t - Move to the top level of the currently displayed manual (and u from here takes you back to the directory)
s - Search incrementally forward, with wrapping, by substring or (Emacs) regexp
C-r - Search incrementally backward, etc., etc.
l, r - Move back and forward, respectively, among the list of nodes you've visited this section
q - Exit the Info viewer
As you see, in a lot of ways Info navigation conceptually corresponds with that in a web browser, especially if itimplements the semantic navigation UI that never really got the love it deserved. (I don't think any current browsers have had that in core for a long time, but there is a Firefox extension that provides them, in the rare case that you actually browse pages which include the metainformation that UI needs in order to work.) But, unlike a browser, Info's UI is so undiscoverable as to be actively hostile to the task-focused user. If you often find yourself struggling with it, perhaps the information here might help.
Funny thing is, quitting is just 'q', or classic ctl-c! Searching is ctl-S.
Also, I can't remember which pretty basic utility has a manpage that indeed redirects to the info page... which is just a copy of the manpage, down to the including the 'see Info page for more'. That said, that may be a packaging issue or just a good old documentation fail.
Ctrl-Q and Ctrl-S are still bad choices for commands. Why? Some terminals support flow control via XON/XOFF, which is Ctrl-S and Ctrl-Q.
Back in the day, with a serial terminal running at 9600 bps, a human had fast enough reflexes to stop and start the screen output. These days, no so much.
Heck, we had an incident just last week where one of my coworkers froze his output screen via Ctrl-S, and I told him about Ctrl-Q to unfreeze it.
It's funny how long some of this stuff hangs around, long past its useful time. Ah, compatibility. Or cruft.
Every now and then I somehow manage to enter Ctrl-S into urxvt and freeze it, still don't know how I do that. Anyway, each time I have to Google "urxvt frozen" to find what to do.
Manpages as "worse is better"? Them's fighting words :) I think it's more an example of how GNU isn't Unix, for better and for worse[1][2].
Info seems to be deeply integrated with the Emacs mindset, so coming from a different editor it's got some learning curve. Except it never seemed to be setup properly by default on a new server, and when I installed something new I'd never remember what I had to do to add it to the root page. Many's the time I tried to info for something and got.. its manpage, but in a crappier setting. Scanning a large manpage with '/' seems far superior to playing whack-a-mole with Info's tree structure. I don't want to sip documentation with a straw, just give me the firehose. (This is also why I prefer 'man zshall' rather than the trying-to-be-helpful sections of the zsh manpage. Who in god's name remembers which of those sections the factoid they're looking for is going to be in?)
All this would be surmountable if Info worked consistently out of the box. But the combination of encountering it only intermittently in working fashion meant that any lessons I learned quickly evaporated, and had to be repeatedly relearnt. I'm very happy now that GNU systems have given up on trying to make Info happen. Documentation quality is all about the quality of the content. Working on the tools instead of the content is classic bikeshedding.
(The one great advance in Unix documentation recently is git's approach of opening the man page when you type --help.)
>have you tried searching for something in, say, Bash's manpage?
I frequently have this problem where I have to wade through a lot of irrelevant matches in less when searching for a keyword in a manpage, and I've been thinking about it for a bit. In my mind, the best solution to the problem is for the manpage authors to be more careful in not using the important keywords elsewhere in the manpage, but in reality, I don't think it's doable to avoid that because what words are important will vary from person to person and even from situation to situation.
Usually my way of finding an answer is to first consult the manpages and if I don't find an answer within a few seconds then I'll just use Google instead. It's a bad habit, I think, because when I'm without internet access -- which actually does happen from time to time, e.g. when I'm on vacation -- I end up having troubles finding out how to do things.
I find searching bash(1) just fine with less(1) and do it quite often. The groff mailing list, the main discussion point for all things troff, is slowly chipping away at adding more semantic information to man pages. The BSDs have been making progress here.
> And it would be really nice if I could read man pages in the terminal in a proportional font, but preserving alignment etc.
Most man utilities can write postscript instead of directly to terminal. You can use that to achieve exactly what you want. Though this is not exactly in the terminal itself.
Is there a way to avoid Times New Roman? Some of the characters are pretty ambiguous. I remember, back when I used that command, I mixed up an l and a 1 for one of the flags.
To be pedantic, the font you're seeing isn't Times New Roman, but rather Times. They're similar, but there are subtle differences.
Yes, you can choose a default font. You need to change your /etc/man.conf, find the line that starts with TROFF, and add new options. For example, to use Palatino as the default font, you should additionally provide the option `-f P`. Then you'll get this output: https://dl.dropboxusercontent.com/u/845567/bash%281%29%20Pal...
This breaks for spacing between non-whitespace character. E.g. the list of flags, which may have varying lengths, but all descriptions start on the same alignment.
This is a man page with a list of flags below
--flag1 Description of flag1
--secondflag Description of secondflag
If we naively replaced the above with 4spaces=1tab we'd get the whitespace between flag1 and its description replaced with two tabs, and we'd get the whitespace between secondflag and its description left as a string of three space characters.
I have no idea what is actually used in man pages for alignment and spacing, but the example above is only to illustrate that 4space=1tab breaks even on trivial examples as a conversion rule.
That does not matter for single dash and letter options. For double dash long options I like to split them on different lines so that you still have a lot of horizontal space for the descriptions themselves even with very ling option names, so a brute force way:
This is a man page with a list of
.I flags
below
.P
.BR --flag :
.RS
Description of flag1
.RE
.P
.BR --secondflag :
.RS
Description of secondflag
.RE
.P
This means that they can be converted to PostScript or PDF. There’s no portable way to do this with the “man” command, but on most Linuxes you can use “man -t” and on a system using Mandoc you can use “man -T pdf”.
Likewise, for HTML, “man -H” is not strictly portable, but only works on certain versions of Linux; a Mandoc system would let you use “man -T html”. (The only strictly portable, as in “POSIX specified,” flag for man is -k.)
Honestly it might be better to just get used to using an existing webpage for your distribution. For example, OpenBSD’s web manpage database (based on Mandoc) is very nice: http://man.openbsd.org/ls.1
Konqueror is still included in current versions of KDE Applications (effectively 5.x, but the term "KDE 5" isn't really used).
Also, it's not so much a Konqueror thing as it is a feature of KDE's URL-handling subsystem. Any KDE application that interacts with URLs can retrieve HTML-formatted man pages. If you don't like Konqueror, you can always use Rekonq. Or you can open the source code in KWrite or Kate. Or you can browse man indices in Dolphin as if they were directories (though the actual pages will open in Konqueror).
KIO slaves are wonderful, wonderful things. It's the same technology that lets you use fish:// to access files and directories over SSH in every KDE program that deals with URLs (and since the file open/save dialogs are URL-based, this means it'll work with anything that uses those dialogs).
Thanks, yeah I used to use fish:/ and fonts:/ and a couple of other kio slaves, just not man, low discoverability I guess. I thought kio slaves had died with KDE5 [that's still the right name IMO despite the framework:applications split].
That assumes that the terminal has full-color support.
It would be even better to use a sane default supported by all terminals (the ugly 16-color one), and enable full-color only on terminals known to support it.
There is probably an exact-but-complicated way to do this. All I do to determine 256-color support is to check for a -256color suffix in the TERM variable.
The terminfo database records how many colours a terminal supports: if the shell command `tput colors` prints 256, then your terminal is configured to support 256 colours.
Unfortunately, there's no standard database field to record the presence of truecolor support; even if there were, there's terminals (like xterm, for example) that understand the control-sequences but map them to the nearest colour in the 256-colour palette rather than using them as-is.
That site needs some updating. The 'features' and 'images' sections both lack content (merely a message stating "under construction"). Although content > style, I can't help but mention how dated the site looks also.
I wouldn't go that far. That and other sections of the website may be incomplete, but the pages load quickly, don't require a multitude of JS calls or other slowdowns. I love pages that do what they're meant to without unwarranted bloat. Gmail and Github use JS for web apps, and that's okay, but a static page doesn't need that and is worse off if they incorporate it. If you go to a random wikipedia article and try to click through references and land on a newpaper's site, 4 out of 5 times the link will be dead. So much for complex CMS installations. I'm (not) sorry that I prefer web pages that work more than ones that chase some short-lived frontend tech.
With all that being said, I'm sure the author would appreciate a contribution to fill in the blanks.
"most" is impossible to search. "mostpager" would have been better with a soft-link from most as default.
Anyway, how do I use it, I've sudo apt install-ed it. Scanning the manpage doesn't give me any great hints e.g. "most /usr/share/man/man1/apt-add-repository.1.gz" brings it up but the manpage shows control data; using as if it were man just fails (it thinks I'm passing it a file).
Just installed most, but it doesn't support scrolling via the j and k keys. I'd have to move all the way over to the arrow keys. This is not a replacement for less. Uninstalling.
First I thought random colors might just be a "because I can" thing, but the script apparently keeps consistent colors for each man page. Now I wonder if it has a use case...
If each man page has different random numbers (perhaps seeded on the man page section and name), then I could see that it might be a memory aid, kinda like having different floors of a building painted different colours, while different layers have different carpeting and different organisations inside the building have different artistic styles: one's subconscious learns what one's environment indicates, and it makes navigation much easier.
Bit of a "useless use of env" here. You don't need the env program for establishing environment variables for the execution of a command. That is a built-in shell feature:
VAR1=val1 VAR2=val2 ... command
However, env here is serving the purpose of avoiding unwanted recursion, because "env man" runs the external man rather than the function. But we can get that with the "command" builtin, or by using "/usr/bin/man":
Really interesting thoughts coming from the groff mailing list:
"Because of poverty owing to neglect -- that is, necessity being the mother of invention -- the author of the article I linked to decided he'd like color in his man pages. Where did he turn? A style sheet in the groff framework, perhaps? Any kind of improvement to the semantic-display connection? No, he reached about as far down as possible, and tweaked the control sequences emitted to the emulator. Because he could. Because, in a way, he had to, insofar as that strange bit of arcania gave him the most leverage.
"So, yes, he's still working with a text terminal, after a fashion. But the programmability of that text terminal is an accident of history, its feature set long since made obsolete -- not useless, but out-moded -- by graphical displays and GUIs. That he reached for that particular tool is a measure of how far we have come, and how far we have not."
For people on OS X I recommend checking out Bwana https://www.bruji.com/bwana/ ,it's not the same thing, it's man pages in your browser but in combination with Alfred (or similar) and/or a terminal plugin it's great. I find it much faster to skim man pages with bwana.
Main issue is of course that this shows man pages for OS X, which is usually similar but not identical to the ones on your favourite distro.
If you like bwana, you could try my updated copy: https://bitbucket.org/tom_seddon/bwana (I've put a compiled version in the releases page - if it doesn't work, you can hopefully build it yourself)
Main improvement: man pages generated with this version include more links. Any time it spots a word that's bold, or underlined, or whatever it is - I don't remember what it was exactly - rather than just printing it that way it tries to turn it into a link to the man page by that name, if there is one.
A good example of how function definitions in shell can be used to overlay commands (applications).
The man() shell function in the example, although slick, is terribly inefficient because every time the man(1) command is called, the function will execute multiple printf(1) applications, over and over and over again. If you've ever ran application startup and shutdown at the assembler level in a debugger, it became obvious pretty quickly than running an application involved many, often recursive libc and system function calls, just to be able to set up the environment in order to start and exit the application.
Here, then, is the fix; this runs only once at shell startup, and stores the resulting escape codes in variables; put this in your ~/.profile (not .kshrc, nor .bashrc, nor .bash_profile, but ~/.profile!):
this code is portable and should work on every Bourne-family shell from the original '70's Bourne shell all the way to ksh93 and bash without modification; if it does not, it is a bug in the shell interpreter. Bug your operating system vendor to fix the interpreter program.
it should be noted that this assumes that the terminal (or the terminal emulator) one is using is actually capable of correctly interpreting the escape command sequences, and in addition correctly displaying them. Not all terminal emulators nor all physical terminals are capable of displaying all, some or any of these display modes. The above also assumes that the shell implements \e, which not all shells do (C-shells notably do not).
Finally, a quick crash course on manual pages, manual pages versus info, and why manual pages are orders of magnitude better, and still a standard, because that is bound to come up sooner or later:
Is there an advantage to overriding the man command over the approach of just directly exporting the env variables in bashrc? I currently do the latter and I don't override the man function. I suppose overriding the man function would allow for man-specific customizations, but perhaps there are other good reasons too?
Are man pages basically just a slab of informally structured prose, or do they stick to some sort of grammar? I.e. Can they be parsed? Can I query one for something like "the meaning of the command line short option -a", or am I stuck trying to use the pager's search functionality for "-a"?
Mandoc, the default manpage formatter in OpenBSD, Illumos, Minix, and some Linux distributions, does semantically parse manpages. The latest version even uses less’s tags functionality to allow jumping to flag definitions. For example, if I “man ls”, I can then type :tx to go to the definition of the -h flag, without hitting any false positives like a text search might.
That is awesome, ... and it cures the stupid underline disease!
What I'm talking about is that text which is marked up as a code (monospaced font) in the troff source being rendered annoying as bold and underlined! That creates ambiguities with actual underline characters and general readability nuisance.
Oh, this is wonderful. For the last few years, I've been going out of my way to add color to my terminal output, making use of things like COPE and zsh-syntax-highlighting. This will be a wonderful addition to that.
Compared to the original formatting, this colorization does the following:
- normal text stays the same color,
- bold text (bright white) becomes red,
- underlined text becomes green,
- inverted text becomes yellow-on-blue
However, if the original does not use bold or underlined text to emphasise parts of the text, this re-formatting has no effect. This is what happens in the curl documentation, where the command-line options are in regular text rather than bold text.
I suppose manpages are another example of "worse is better". They are extremely simple to use, which is what you want when you're frustrated and looking for that *$#& option to 'find'. And yet, the troff/groff formatters used by manpages can be pretty sophisticated (Kernighan mentioned in an interview [1] he still used it to write books, eschewing to complexity of Latex) and can produce a variety of formats, such as HTML or PostScript. Why don't distributions make more use of this? I miss the days where you could "man foo" in KDE's quick launch bar and get a nicely HTML formatted version in Konqueror.
[1] https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.h...