Reading docmentation

Reading documentation is an art, and can be very enjoyable if it is well written.

As a software developer, one of my aims is to write documentation that people should want to read, while designing systems that work well without having to read the documentation. Seemingly opposite goals.

I have a habit of reading documentations. And when I say reading, I mean thoroughly.

One of my earliest memories with computers was me failing to jump between buildings in a spiderman game, giving up, and spending time reading windows help. I have read almost every single page in windows help for XP, back then.

It was the beginning of a habit. When I started programming in python, which was after entering college, I read python 2.7 documentation. Every single line from every single page. All the functions in all builtin modules, changelogs, what’s new, guides, the whole deal. It changed me. I would write programs very differently.

The habit persisted. Pretty much any technical document I read, I read it in entirety. A friend commented that I was incapable of skimming things. He did not imply it was necessarily a bad thing.

Among other documentations I’ve read are a few notable ones – Docker, Erlang, Bash, git. Did you know Bash can do tcp/udp communications by writing to special psuedo files, and : is a valid command, bash’s own noop, handy for commenting blocks of code?

Elasticsearch joins this list tomorrow. I’m close to completing a new set of docs – something larger than a hundred pages – after long. Feels good.

Advertisements

Pentadactyl – My secret firefox superpower

I always hated having to move my hands off keyboard to get things done. I love key bindings. After having tried many extensions, I stumbled upon vimperator. It was simply awesome, all I wanted and some more. Unfortunately, it was a bit buggy and I had to abandon it. I missed it for long, until recently, I stumbled upon its fork, pentadactyl, almost by accident.

Pentadactyl uses vim key bindings in firefox, gets GUI rid of all clutter, gives me an extremely powerful scripting interface, and works without a glitch. Everything is customizable, as it should be. I was a fan of vim since long. The composable commands, scripting interface, and a vast collection of plugins made it my favorite editor. I am obsessed with vim. I emulate it everywhere I can. tmux for terminal session management, vimpc for music, and pentadactyl in firefox, vi emulation in eclipse, the list goes on.

For those of my friends who marveled at my firefox use, navigating everywhere with lightning speed, using a command line interface or succinct key bindings for all operations, for those of you obsessed with the simplicity and power of vim, here’s my secret superpower. Pentadactyl. If you are a regular vim user, it should take you just a few minutes to get the ball rolling, you can thank me later.

I’ve started building my .pentadactylrc file very recently. Any tips are most welcome.

On a semi related side note, if you do any serious programming, you need to learn how to use a decent editor. I prefer vim, but emacs is perfectly fine too. If you are thinking of notepad, get away from me before I hit you hard.

My first adventure with phusion passenger

I spent more than a day stuck with using phusion passenger for a production deployment of an app I made for a client. This is a short note to remind myself of it in future and to help anyone stuck with the same.

The symptoms were pretty bad. Phusion passenger “simply did not work” with nginx. The standalone mode works like a charm, but nginx integration mode gives me directory listings, serves files in public, but does not start the app at all. Nothing in nginx logs to help. The server config is perfectly fine, checked it a hundred times, and tried a bazillion variations.

The problem: A missing passenger_root directive in http block of nginx.conf. I haven’t found anywhere that it is necessary, and given that I used phusion passenger’s repository to install nginx and passenger, I expected the setup to work out of the box.

If your passenger-deployed app doesn’t seem to start at all, just check if your http block has the passenger_root directive. In my case, it had to be set to /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini.  It might be different in your case, just do a locate phusion_passenger/locations.ini to get the appropriate path.

After two days of scratching my head, reading through nginx and passenger docs a dozen times, just added it on a whim and it now works! I can now sleep in peace.

Also, look at passenger_nodejs if you use nvm. You don’t need system-wide node if your passenger_nodejs points to the proper node binary.

This post also highlighted the need for better config If I intend to blog about code. Not being able to visually distinguish code-snippets and inlined commands is a big bummer.

Recursion in livescript

I have been looking at JavaScript, and languages that compile to JS. Coffeescript was my first love in this domain, and I have very recently transitioned to LiveScript, just a few months ago.

Until now, I was not faced with a problem for which recursion is the most natural solution. A couple of days go, when I was writing this program to test for a palindromic number, a recursive implementation seemed the most sensible approach. LiveScript being my new found love, I fired up vim, and… blank.

I tried searching on google, but it turned up nothing useful. I spent almost half an hour reading livescript and prelude, to find these two solutions. Turns out that you can use the keyword function to create named functions, which get hoisted as usual with javascript.

function fib x
   if x<0 then throw new Error
   if x<3 then x
   else fib(x-1)+fib(x-2)

Or, you can use the fix function from prelude to do anonymous recursion. This is the first time I saw the beautiful Y combinator being used this way. And I had to read my old notes on Y combinators and Javascript call and apply to understand the magic of what is happening.

require! 'prelude-ls'.fix

fib = fix (fib) ->
   (x) ->
       if x < 0 throw new Error
       if x < 3 then x
       else fib(x-1) + fib(x-2)

Looks similar? Nope. Here, fix takes a function that returns a function as an argument, and returns a function that is the inner function, with the outer argument referring to the inner function itself. Did that make any sense? 😀

The beauty of this approach is that the function fib doesn’t get hoisted, it is just an ordinary variable assignment, not a named function, and we just did anonymous recursion!

Don’t know if the sound of it excites you, but I sure am excited. Recursion in an anonymous function? Isn’t that cool?

Actually, looks like one of the common applications of Y combinator is to do anonymous recursion, but I didn’t think of it earlier.