How to view differences between the man pages for different versions of the same program

diff()man

Whenever I am upgrading one of my Linux boxes (i.e. installing the next version of my favorite distribution), upgrading the respective configuration files always has been very time consuming, because in many cases I don't just alter the distribution's default configuration files to reflect my situation, but I have crafted my own configuration files very carefully.

Until now, when upgrading, in these cases I either have read the respective man pages completely from scratch and have made new configuration files from scratch (this is clean, but costs much effort), or I have compared (think diff) the old and the new distribution's default configuration files, and when I saw a difference which could be important, I have "ported" (merged) it into my own configuration file (I am not happy with that method for several reasons, one of them being that the maintainer could have ignored a new configuration directive which could be dangerous to ignore in my case; but it hasn't been always avoidable if I was in hurry).

I always have asked myself how other people cope with that problem. One idea would be to compare the man page of the old version of a software to that of the new version, thus seeing all differences in configuration directives or methods immediately.

So here is the question: Does anybody know about a specific diff viewer for man pages, notably for the text console (main scenario would be working via SSH without X)?

Please note that I am aware that there are many diff viewers (I have read dozens of articles and Q & A about this subject). My question is specifically about diff viewers for man pages which offer some comfort (for example, you tell it the base directory of the old man pages and then only have to say "show diff sshd_config" or the like).

I am also aware that I eventually could read the change log of the respective upstream, but I have seen many cases where you couldn't rely on it (i.e. not all changes were mentioned there), it's much more inconvenient, and some distributions heavily patch the upstream, so I would say that this is not really an option. Comparing the old version's source code with the new one only for finding out about new configuration options seems too much and perhaps is impossible in case of Apache, Sendmail and the like. In contrast, comparing the man pages seems reasonable (if possible).

Any ideas?

Best Answer

Man pages, once changed to a human-readable form, are text files that you can diff with whatever tool that suits you. Here are two examples, as two bash functions, for two tools: diff and vimdiff. Adapt them to your favorite tool.

With vimdiff:

vimdiff_man() { vimdiff -R <(man --manpath="/old/path/to/man" "$1") <(man "$1"); }

With diff, side by side, adjusted to your screen width:

diff_man() (
    width="${COLUMNS:-80}"
    export MANWIDTH=$((width / 2 - 2))
    diff -y -W"$width" <(man --manpath="/old/path/to/man" "$1") <(man "$1") | less
)

In each function, I'm diffing between two pseudo files <(...), each of which containing the result of the man command between parentheses (this is bash's Process Substitution).

/old/path/to/man is the directory hierarchy containing your old manual pages. It is expected to have the same secondary man levels man1, man2, ... as your main manual directory (probably /usr/share/man). Change it to fit your needs.

Usage:

diff_man sshd_config
vimdiff_man sshd_config
Related Question