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  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.
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.
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.
This is the Info main menu (aka directory node).
A few useful Info commands:
'?' 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.
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.
1. man something
2. discover that something is a gnu utility whose authors decided to support by pointing its minimal manpage to an info page.
3. info something
6. ctl-g (trying to "Cancel the current operation")
11. ctl-alt-g (I got a "Quit" message!)
$ pkill info
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.
Except if the app opened the terminal in raw mode, in which case the app gets the control character.
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.)
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.
LESS_TERMCAP_mb=$(printf "\x1b[38;2;255;200;200m") \
LESS_TERMCAP_md=$(printf "\x1b[38;2;255;100;200m") \
LESS_TERMCAP_me=$(printf "\x1b[0m") \
LESS_TERMCAP_so=$(printf "\x1b[38;2;60;90;90;48;2;40;40;40m") \
LESS_TERMCAP_se=$(printf "\x1b[0m") \
LESS_TERMCAP_us=$(printf "\x1b[38;2;150;100;200m") \
LESS_TERMCAP_ue=$(printf "\x1b[0m") \
(See also, a script to display an image in the terminal: https://git.gnome.org/browse/vte/tree/perf/img.sh?h=vte-0-36 )
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.
Example: I don't have zsh for comparison but on my OS X machine, running `man -t bash | open -f -a Preview` results in this: https://dl.dropboxusercontent.com/u/845567/bash%281%29.pdf
Here's zsh: https://drive.google.com/file/d/0B_jWp8d11aB5Wi15eVdJS1Nhdk0...
It kinda sucks that you can't just pipe directly to Preview, but I suppose we should be grateful this wonderful pipeline does actually work!
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...
And there's an interesting history to that split: https://en.wikipedia.org/wiki/Times_New_Roman#Linotype_relea...
People would need to use tabs (gasp) instead of spaces for that :-P
That would be madness.
This is a man page with a list of flags below
--flag1 Description of flag1
--secondflag Description of secondflag
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.
This is a man page with a list of
.BR --flag :
Description of flag1
.BR --secondflag :
Description of secondflag
$ man tbl
Since you want proportional fonts, you'd have to be willing to leave the terminal already. If so, I'm aware of three options:
1. the classic, xman: fugly
2. the builtin, "man -H": it works sometimes. On my own system, the it's so unreliable that I'd call it alpha-stage software
3. and Konqueror. Works perfectly every time, but you'd have to install KDE components.
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
For that matter, any KDE application that handles URLs can retrieve HTML-formatted man pages thanks to KIO slaves.
You want the source of the HTML-formatted man page so you can edit it and save your edited copy? OK:
$ kwrite 'man:/usr/share/man/man1/ls.1p.gz'
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).
Unfortunately, it looks like fonts:/ was never ported to KF5, but fish:// and a bunch of others are still around.
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.
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.
As it should (assume and have) in 2016.
With all that being said, I'm sure the author would appreciate a contribution to fill in the blanks.
The official website doesn't really contain any information.
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).
Hint? Or do I need to read the source ...
or for my fish friends, add to ~/.config/fish/config.fish
set -x PAGER most
This'll use `most` everytime a pager is needed (i.e. git log), if you want to use `most` only for man pages, replace PAGER with MANPAGER
set -Ux PAGER mostU
If you prefer to keep fish.config cleaner, that is :)
Space and backspace are equivalent to page down and page up.
It works so well it is unsane not to use it.
Thank God I saw that name while installing Slackware a long time ago, and since then it had been a pleasure to use.
VAR1=val1 VAR2=val2 ... command
LESS_TERMCAP_mb=$(printf "\e[1;31m") \
LESS_TERMCAP_md=$(printf "\e[1;31m") \
LESS_TERMCAP_me=$(printf "\e[0m") \
LESS_TERMCAP_se=$(printf "\e[0m") \
LESS_TERMCAP_so=$(printf "\e[1;44;33m") \
LESS_TERMCAP_ue=$(printf "\e[0m") \
LESS_TERMCAP_us=$(printf "\e[1;32m") \
command man "$@"
"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."
Thread root: https://lists.gnu.org/archive/html/groff/2016-08/msg00013.ht...
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.
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.
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!):
LESS_TERMCAP_mb=`printf "\e[1;31m"`; export LESS_TERMCAP_mb
LESS_TERMCAP_md=`printf "\e[1;31m"`; export LESS_TERMCAP_md
LESS_TERMCAP_me=`printf "\e[0m"`; export LESS_TERMCAP_me
LESS_TERMCAP_se=`printf "\e[0m"`; export LESS_TERMCAP_se
LESS_TERMCAP_so=`printf "\e[1;44;33m"`; export LESS_TERMCAP_so
LESS_TERMCAP_ue=`printf "\e[0m"`; export LESS_TERMCAP_ue
LESS_TERMCAP_us=`printf "\e[1;32m"`; export LESS_TERMCAP_us
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:
I thought if you just prefixed the eventual 'man "$@"' with those environment variable settings that it would have the same result.
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.
With these settings, the underlining is gone.
- 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.