Beware, this would be slightly longish.
Debian Contributions
In the last couple of weeks, was lucky to put up a patch against debian-policy which had been bothering me for a long-long time.
The problem statement is simple, man-pages historically were made by software engineers for software-engineers. The idea, probably then was you give the user some idea of what the software does and the rest the software engineer would garner from reading the source-code. But over period of time, the audience has changed. While there are still software engineers who use GNU/Linux for the technical excellence, the man-pages have not kept up with this new audience who perhaps are either not technically so sound that or they do not want to take the trouble to reading the source-code to understand how things flow. An ‘example’ or ‘examples’ in a man-page gives us (the lesser mortals) some insight as how the command works, how the logic flows.
A good example of a man-page is the ufw man-page –
EXAMPLES
Deny all access to port 53:
ufw deny 53
Allow all access to tcp port 80:
ufw allow 80/tcp
Allow all access from RFC1918 networks to this host:
ufw allow from 10.0.0.0/8
ufw allow from 172.16.0.0/12
ufw allow from 192.168.0.0/16
Deny access to udp port 514 from host 1.2.3.4:
ufw deny proto udp from 1.2.3.4 to any port 514
Allow access to udp 1.2.3.4 port 5469 from 1.2.3.5 port 5469:
ufw allow proto udp from 1.2.3.5 port 5469 to 1.2.3.4 port 5469
Now if we had man-pages like the above which give examples, then the user at least can try to accomplish whatever s/he is trying to do. I truly believe not having examples in a man-page kills 50% of your audience and people who could potentially use your tool.
Personal wishlist – The only thing (and this might be my failure) is we need a good way to search through a man-page. The only way I know is using ‘/’ and try to give a pattern. Lots of times it fails because I, the user doesn’t know the exact keyword which the documenter was using. What would be nice, great if we do have some sort of parser where I tell it, ‘$this is what I’m looking for’ and the parser tries the pattern + all its synonyms and whatever seems to be most relevant passage from the content, in this case – a manpage it tells me. It would make my life a lot easier while at the same time force people to document more and more.
I dunno if there has been any research or study of the relationship between good documentation and popularity of a program. I know there are lots of different tiny bits which make or break a program, one of which would definitely be documentation and in that a man-page IF it’s a command-line tool.
A query on Quora gives some indication https://www.quora.com/How-comprehensible-do-you-find-Unix-Linux-Man-pages although the low response rate tells its own story.
there have been projects like man2html and man2pdf and others which try to make the content more accessible to people who are not used to the man-page interface but till you don’t have ‘Examples’ the other things can work only so far. Also if anybody talks about X project which claims to solve this problem they will have to fight manpages who have been around like forever.
As can be seen in the patch, did some rookie mistakes as can be seen. I also filed a lintian bug at the same time. Hope the patch does get merged at some point in debian-policy and then a check introduced in lintian in some future release. I do agree with anarcat’s assertion that it should be at the level of the manpage missing level.
I am no coder but finding 14,000 binary packages without a manpage left me both shocked and surprised.
I came to know about manpage-alert from the devscripts package to know which all binary packages that have been installed but not have man-pages.
I hope to contribute a manpage or two if I across a package I’m somewhat comfortable with. I have made a beginning of sorts by running manpage alert and putting the output in a .txt file which I would grep through manually and see if something interesting jumps at me.
The learning garnered from putting the patch to the debian package resulted in another patch but this time for an upstream project altogether. As can be seen all are just baby-steps that even a non-coder can take.
Another couple of bugs I filed which were fixed were of a sim called ‘unknown-horizons’ . A 2D realtime strategy simulation. I had filed three bugs, two of which were fixed in 2 days, the 3rd I hope is also fixed soonish.
Lastly, I spent most of the week-end poring over packages who have left files in /etc/bash_completion.d/ . I spent almost 4-5 odd hours as each package in question as well as entries found in /etc/bash-completion.d/$filename I had to find which package it belonged to first –
[$] dpkg -S /etc/bash_completion.d/git-prompt
git: /etc/bash_completion.d/git-prompt
I know that dpkg-query also does the same –
[$] dpkg-query -S /etc/bash_completion.d/git-prompt
git: /etc/bash_completion.d/git-prompt
But I am used to plain dpkg although do know that dpkg-query can do lot more intimate searching in various ways than dpkg can.
Once the package name was established, first simulate the purge –
[$] sudo aptitude -s purge git
[sudo] password for shirish:
The following packages will be REMOVED:
git{p}
0 packages upgraded, 0 newly installed, 1 to remove and 14 not upgraded.
Need to get 0 B of archives. After unpacking 29.5 MB will be freed.
The following packages have unmet dependencies:
libgit-wrapper-perl : Depends: git but it is not going to be installed
git-extras : Depends: git (>= 1.7.0) but it is not going to be installed
bup : Depends: git but it is not going to be installed
git-remote-gcrypt : Depends: git but it is not going to be installed
git-svn : Depends: git (> 1:2.11.0) but it is not going to be installed
Depends: git ( 1:2.11.0) but it is not going to be installed
Depends: git (= 1:1.8.1) but it is not going to be installed
git-core : Depends: git (> 1:1.7.0.2) but it is not going to be installed
The following actions will resolve these dependencies:
Remove the following packages:
1) bup [0.29-2 (now, testing, unstable)]
2) fdroidserver [0.7.0-1 (now, testing, unstable)]
3) git-annex [6.20161012-1 (now, testing)]
4) git-core [1:2.11.0-2 (now, testing, unstable)]
5) git-extras [4.2.0-1 (now, testing, unstable)]
6) git-remote-gcrypt [1.0.1-1 (now, testing, unstable)]
7) git-repair [1.20151215-1 (now, unstable)]
8) git-svn [1:2.11.0-2 (now, testing, unstable)]
9) gitk [1:2.11.0-2 (now, testing, unstable)]
10) libgit-wrapper-perl [0.047-1 (now, testing, unstable)]
11) python3-git [2.1.0-1 (now, testing, unstable)]
12) svn2git [2.4.0-1 (now, testing, unstable)]
Leave the following dependencies unresolved:
13) devscripts recommends libgit-wrapper-perl
14) dh-make-perl recommends git
15) fdroidserver recommends git
16) git-annex recommends git-remote-gcrypt (>= 0.20130908-6)
17) gplaycli recommends fdroidserver
18) python-rope recommends git-core
Accept this solution? [Y/n/q/?] q
Abandoning all efforts to resolve these dependencies.
Abort.
Then I made a note of all the packages being affected, saw purging all of them wouldn’t call others (the Package dependency Hell), made the purge and then reinstalled anew.
The reason I did this is that many a times during upgrade, either during update/upgrade sometimes the correct action doesn’t happen. To take the git’s example itself, there were two files git-extras and git-prompt which were in /etc/bash_completion.d/ both of which were showing their source as git. Purging git and installing git afresh removed git-extras file and git-prompt is the only one remaining.
While blogging about the package, did try to grep through changelog.Debian.gz and changelog.gz in git –
┌─[shirish@debian] - [/usr/share/doc/git] - [10046]
└─[$] zless changelog.gz
and similarly –
┌─[shirish@debian] - [/usr/share/doc/git] - [10046]
└─[$] zless changelog.Debian.gz
But failed to find any mention of the now gone git-extras. Doing this with all the packages took considerable time as didn’t want to deal with any potential fallout later on. For instance, ufw (uncomplicated firewall) also had an entry in /etc/bash_completion.d/, hence before purging ufw, took backup of all the rules I have made, did a successful simulation
[$] sudo aptitude -s purge ufw gufw
The following packages will be REMOVED:
gufw{p} ufw{p}
0 packages upgraded, 0 newly installed, 2 to remove and 14 not upgraded.
Need to get 0 B of archives. After unpacking 4,224 kB will be freed.
Note: Using 'Simulate' mode.
Do you want to continue? [Y/n/?] y
Would download/install/remove packages.
purged the packages, reinstalled it and then re-added all the rules. Doing it all for various sundry packages, had to do it manually as there is no one size fits all solution.
A sensitive one was grub which still has an entry in /etc/bash_completion.d/grub. Doing it wrong could have resulted in a non-bootable situation. There are workarounds for that, but it would have taken quite a bit of time, energy, notes and bit of recall factor what I did the last time something like that happened. Doing it manually, being present meant I could do it rightly the first time.
So, was it worth it – It would be if the package maintainers do the needful and the remaining entries are moved out of /etc/bash_completion.d/ to /usr/share/bash-completions and some to my favourite /usr/share/zsh/vendor-completions/ – for instance –
┌─[shirish@debian] - [/usr/share/zsh/vendor-completions] - [10064]
└─[$] ll -h _youtube-dl
-rw-r--r-- 1 root root 3.2K 2016-12-01 08:48 _youtube-dl
But trying to get all or even major packages to use zsh-completions would be hard work and would take oodles of time and this concerns upstream stuff, also very much outside what I was sharing.
World History
Before, during and even after South-African experience, I was left wondering why India and South Africa, two countries who had similar histories at least the last couple of hundred years or more, the final result of Independence was so different for both the countries. It took me quite sometime to articulate that in a form of question , while the answers were interesting, from what little I know of India itself, if I were an Englishman I would never leave ‘Hindustan’. What the people answering failed to take into account was that in that era it was ‘Hindustan’ or un-divided India.
Pre-partition map of India
This map can be found at https://commons.wikimedia.org/wiki/File:British_Indian_Empire_1909_Imperial_Gazetteer_of_India.jpg and is part of quite a few Indian articles. I would urge people to look at the map in-depth. Except for the Central India Agency and Central India Provinces, most of the other regions were quite comfortable weather-wise.
Hence I can’t help but feel the assertion that Britishers didn’t like India (as to live here) slightly revolting. See the excerpt/take on Dale Kennedy ‘s The Magic Mountains: Hill Stations and the British Raj. Berkeley: University of California Press, 1996. xv + 264 pp. . A look at the list of hill stations of divided India is enough to tell that there were lot of places which either were founded by the Britishers or they chose to live there. And this is not all, there are supposed to lot of beautiful places even in Pakistan, especially in North East Frontier, Swat for instance. While today it’s infamous for Taliban and Islamic Terrorism, there was a time it was known for its beauty.
The second most difficult mountain in the world – K2, Pakistan
Trivia – After Everest, K2 is the smaller one although whatever I have read of people’s accounts, most people who ascended all 14 8,000 metre peaks say K2 is technically more tougher than Everest and after Everest has the highest casualty rate.
Also places like the disputed North half of Pakistan Occupied Kashmir, Gilgit–Baltistan, Extreme northern Punjab of Pakistan , Northern half of Khyber-Pakhtunkhawa province and Northern Balochistan all of these places would have been more than conducive to the Britishers as it is near to the British climate (snow and pleasant weather all year round). It really is a pity that Pakistan chose to become a terrorist state where it could have become one of the more toured places of Asia. I really feel nauseous and sad at the multiple chances that Pakistan frittered away, it could have been something else.
Filed under: Miscellenous Tagged: #bash-completion, #British Raj, #contributions, #debian, #debian-policy, #Debian-QA, #Hill Stations, #India Independance Movement, #lintian, #obsolete-conffiles, #unknown-horizons, #weather, #World History, adequate, Pakistan, tourism
