4

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?

  • 1
    One way people cope (and I realize it might not work for you since you create the config files from scratch) is to use a configuration manager like puppet. This leverages the work other people have done to understand the details of the config files through many versions and distro customizations of a particular utility. So (ideally) all you have to do is specify your configuration choices at a high level and the software will figure out the right way to modify all the config files. – Mark Plotnick Jan 17 '17 at 0:32
7

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
  • 1
    BTW diff -y gives a nice side by side comparison of the two documents. – George Vasiliou Jan 17 '17 at 7:42
  • 1
    @xhienne This answer definitely would deserve several hundreds of reputation. Thanks to you, I have learned something new about bash. For all those who don't immediately understand how the above works (no, these are not redirections, because that wouldn't work here): man bash, section EXPANSION, subsection Process Substitution. – Binarus Jan 17 '17 at 9:47
  • @GeorgeVasiliou Good idea. Answer changed. – xhienne Jan 17 '17 at 11:34
  • 1
    @Binarus Thank you for your comment. I have added something about Process Substitution in my answer. Hope this is OK. – xhienne Jan 17 '17 at 11:37
  • 1
    @Binarus Oh, I didn't notice that diff -y was truncated indeed. I have corrected the diff_man function. I made it figure out the screen width instead of fixing it to an arbitrary number. And instead of fold, I have asked man to adjust to the width, which keeps formatting intact. Thanks for the suggestion. – xhienne Jan 17 '17 at 15:29
2

Sorry guys, i could not resist on this... Modifying the accepted answer like this:

diff -y -w -W 150 <(links -dump  "http://man.he.net/?topic=grep&section=all" |less |fold -s -w 70) <(man grep |less |fold -s -w 70)

You can compare side by side local installed man pages to online man pages .... I just like it and thought to share it.

Offcourse you can replace man.he.net with your favorite online manpage viewer (i.e https://manpages.debian.org).

Also this even works nice:

diff -y -w -W 150 <(links -dump "https://www.mankier.com/?q=grep" |less |fold -s -w 70) <(man grep |less |fold -s -w 70)

PS: -w is necessary to ignore all white space and compare just lines. less is used in both cases for a uniform format during reading and comparison.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.