Search this site





How not to write documentation.

I've grown accustomed to ruby having poorly accessible documentation. What I mean by 'poorly accessible' is the fact that ri Array gives me a list of things Array can do (which is nice), but to actually find out about Array.delete I have to run ri Array.delete. Further, the online ruby documentation is better, but not great, but is somehow strangely different from simply the rdoc itself. I got used to Python's often-helpful ways of pydoc showing you what appears to be "as much as possible" when you pydoc a class, module, or method.

Maybe I'm doing it wrong. Either way, the following is annoying and unhelpful. While it tells me the arguments that should be passed, and what is returned, it doesn't help me really know more about the function. Luckly, I'm already familiar with select from other languages.

snack(~) % ri
------------------------------------------------------------- IO::select 
     [, write_array 
     [, error_array 
     [, timeout]]] ) =>  array  or  nil
     See +Kernel#select+.
Ok, fine... Let's look at Kernel#select.
snack(~) % ri Kernel#select
---------------------------------------------------------- Kernel#select 
     [, write_array 
     [, error_array 
     [, timeout]]] ) =>  array  or  nil
     See +Kernel#select+.

Week of unix tools!

This past week of work had me stretching my piping-ninja skills to the limits. In the past 4 days, I have created a oneliner that invoked xargs 3 times in a series of piped expressions, a oneliner that had xargs calling xargs, a oneliner that was well over 1000 characters and invoked sed, xargs, grep, perl, awk, xpathtool and others, sometimes twice, and several other ninja-like uses of filter-fu involving unix pipes. It's been a fun week for oneliners.

So, I thought I might spend the next 7 days covering some of the tools I find myself working with almost every day. I hope to cover all the ways I use a given tool, when it should be used over any alternatives, things to look up in the manpage, etc.

I'll try to cover more than one tool per day, because some tools can be batched together because there isn't much to day other than "this is useful for foo, bar, anz baz".

Tentative, incomplete list:

data sources
cat, GET, echo, nc (netcat), shell command substitution
cut, grep, paste, sed, sort, tr, uniq, wc
xargs, sh, awk, perl (for oneliners)
Here's a sneak peek at what you might learn:

'sort' can sort lines, right? But how do you sort words on the same line?

% echo "one two three four five" \
  | xargs -n1 | sort | xargs
five four one three two
Some of you might notice that the xargs(1) invocations can be replaced with tr(1). Yes. I use xargs(1) because it's less typing and handles many case tr(1) won't. This is not to say tr(1) doesn't have it's wonderful uses. More on that later this week ;)

If you have suggestions, let me know.