Using the Word Cloud Generator program

If the computer is a magic box for you, then the next step in our process may be somewhat scary, because it involves downloading an application from our course’s Moodle site that does not have a GUI (a graphical user interface). The Word Cloud Generator, courtesy of IBM, is a Java applet that runs on the command line.

In fairness, there are other options out there. They include, for PC users, a free application called Wordaizer, at the very least. Or you can always use the Processing language to create you own word clouds. Someone has developed WordCram which you can use as a basis from which others can start.

First, you need to find the downloaded file, which should be a zip archive. Most modern operating systems should have the necessary applications to unzip the file – if your doesn’t, then look for a good archive utility that handles zip, gzip, tar, and other forms of compression on a site like MacUpdate or some other reliable source for software.

The unzipped file turns out to be a folder. Inside the folder you are going to see the following:

  • a directory (folder) labelled examples
  • a directory labelled license
  • the actual word cloud generator application: ibm-word-cloud.jar
  • a read-me file, readme.html
  • a Windows batch file named run-example.bat
  • a Unix shell script named run-example.sh

I am writing this from a computer running Mac OS X, which is a Unix machine with a pretty face, and so I am going to use the Unix shell script as my foundation, but the corresponding steps should work similarly for those of you running Windows OS and using the batch file. (Properly, I believe I should describe Mac OS X as POSIX-compliant, but I don’t know how many people, including myself, would understand at all what that meant.)

The readme file is somewhat helpful, but I find two documents (files) to be even more helpful. One is the shell script itself, which gives me an exact idea of what I should type — or, better, paste — into a terminal to begin to get results. And so the first thing you should do is copy the shell script, start with java and copy all the way to example.png into an open terminal window and hit return.

If you haven’t used the terminal before, or whatever your OS calls getting access to the command line, then you are in both for something of a shock as well as a real treat. The shock will come from something that looks, for those of you raised in the era of GUIs, so, well, textual, and the treat will come with realizing that even though its textiness seems so foreign, it’s actually fairly easy to use and you will be surprised how quickly you are going to get results.

And so, perhaps, the first place to begin is finding out where to find this Terminal application: in Mac OS X, it’s in the Utilities directory/folder within the Applications directory, which is at the root directory. The file hierarchy looks something like this:

/Applications/Utilities/Terminal.app

You read this as follows:

  • / (root)
  • Applications/ (Applications directory)
  • Utilities/ (Utilities directory)
  • Terminal.app (application named Terminal)

Okay, now you have the Terminal application open, which means you have a window on your desktop which contains something like this:

Last login: Wed Mar 30 16:51:05 on console  
[~]%

The % is known as the prompt, which is short for “the command line prompt”, which means you are now working with the command line interface (CLI). Congratulations, you have just earned your first CLI credit.

Your prompt may very well be longer: I have shortened mine so that it places my current working directory between square braces and then gives me a percentage sign to tell me it’s ready to receive instructions. (There’s a lot more to say about the environment in which you now find yourself, but for the sake of getting on with this tutorial we will leave that for another time.)

If you paste the code that you copied out of the shell script above and try to run it from where you are, chances are you will get nothing. That is because the prompt can only run things when it knows where they are — much the same applies in the GUI, but Windows and Mac and Linux GUIs do a lot of work behind the scenes to find applications for you. You have two choices: add the file hierarchy to your command or to navigate to where the WCG application is and run it from within its directory. (If you were going to use the application a lot, there are some other considerations, but we will leave those for another time — but feel free to ask if you like.)

Typically, most Terminal windows will start you in your user home directory — which is indicated by the use of the tilde (~). My best advice for the sake of this current activity is to use Windows Explorer or the Mac Finder and move the unzipped folder containing the WCG, which is named “IBM Word Cloud” in my case, to the Desktop o TRUNCATED! Please download pandoc if you want to convert large files.

Advertisements