Zen Koans

Buddha screen shot
Yin Yang screen shot

I have been using display-dhammapada for some time now but I have always wanted a similar program for zen koans.

I came across a perl module on CPAN , “Zen Koans” and it was a nice start.

From there I added 2 more koan collections, The Gateless Gate and The Blue Cliff Record, and wrote a wrapper script for these collections.

The wrapper script, “zen” has several options including printing to the terminal (similar to fortune or display-dhammapada), formatting the output to html, to be included in a web page, and printing the output to ~/koan.html to be viewed in firefox (or other browser).

For an example of the script on a web page see : tenach’s blog (thank you tenach for putting this up).

When printing to ~/koan.html , there are several themes.

To use these koans, you will need to download zen-koans.tar.gz
md5sum sha1sum.

Assuming you have downloaded zen-koans.tar.gz to ~/Downloads, you can either extract the file with a graphical tool (Archive Manager) or the command line.

cd ~/Downloads
tar xzvf zen-koans.tar.gz

Detailed instructions, and a description of the options, are included in the README.

gedit ~/Downloads/Zen-Koans/README

To install on Ubuntu (Instructions for Fedora are in the README):

cd ~/Downloads

#copy the perl modules
sudo mkdir -p /usr/local/share/perl/5.10.1
sudo cp -R Zen-Koans/Zen /usr/local/share/perl/5.10.1

#copy the images
sudo mkdir /usr/local/share/images
sudo cp Zen-Koans/images/* /usr/local/share/images

#copy the wrapper script
sudo cp Zen-Koans/bin/zen /usr/local/bin
sudo chmod +x /usr/local/bin/zen

To try out the application try:

zen -ab && firefox ~/koan.html

For additional options , help is available with the -h flag:

bodhi@maverick:~$ zen -h

This program prints a random koan form one of 3 collections
of koans :

Shaseki-shu (Collection of Stone and Sand) - Default
The Gateless Gate
The Blue Cliff Record

The Shaseki-shu koans are easiest to comprehend, 
The Gateless Gate are intermediate,
and The Blue Cliff are most difficult.

The default behavior is to print to the terminal

usage: zen [options]

 -h | --help     : this (help) message.
 -c | --cliff    : Use the Blue Cliff Record.
 -g | --gate     : Use the Gateless Gate.
 -a | --about    : Print information about the collection (first koan). 
 -i | --include  : Prints the koan with (basic) html formatting.
 -b | --buddha   : Prints the koan to ~/koan.html , view with firefox.
 -f | --forest   : Same as -b, forest BG image.
 -s | --stones   : Same as -b, zen_stones BG image.
 -y | --yinyang  : Same as -b, yin-yang BG image.
 -d | --dark     : Prints to ~/koan.html , dark BG, no image.
 -l | --light    : Prints to ~/koan.html , light BG, no image.
 -o | --gold     : Prints to ~/koan.html , gold BG, no image.
 -r | --random   : Prints to ~/koan.html , random koan/theme.

I hope you enjoy them =)

Be careful, I am afraid they can be addicting.

If anyone would like to offer improvements or help package them into a ppa , assistance would be appreciated (pm me on the Ubuntu Forms). Otherwise I will try to package them into a ppa as time allows.

This entry was posted in Linux, Zen. Bookmark the permalink.

19 Responses to Zen Koans

  1. fonzie says:

    Are you planning on uploading this to CPAN, making it available to the larger community via the same mechanisms as Zen::Koans rather than hosting it yourself on this site.

    This isn’t a good way to install perl modules. Use one of the module creation modules to create a proper package which people can install by:
    perl Makefile.PL or via the cpan client.

  2. Martin Owens says:

    We should help you package it all up so it’s not so tiresome to install. could MOTU help at all?

  3. bodhi.zazen says:

    Thank you Martin, any assistance would be appreciated.

  4. bodhi.zazen says:

    fonzie: Yes I would like to make the package more “available”, any guidance or assistance you can offer would be appreciated.

  5. zengargoyle says:

    i took a poke about your code. pretty neat idea, i liked it so i re-wrote it. :)

    you can find zen-koans-zg.tar.gz at the website if you want to take a look. i’ve been doing Perl for too many years to count so i cleaned it up the way i would have written it mostly. didn’t want to get into rewriting the Zen::* modules that much, just made enough changes to make it easier to work with.

    if you want to make a .deb backage, look at the SelfControl package on the same site, it’s not perfect, but it does have the full Perl module build/test/install/debhelper stuff in it. somehow it magically ended up in the Software Center.

    anyways, take a look if you like.

  6. Martin Owens says:

    Bodi, you need to approve our comments so we can see what other people have written… otherwise it looks like your talking to yourself ;-)

  7. marto says:

    Hey there, nice to see some Perl on planetubuntu.

    Installing via CPAN is preferable for several reasons, it can fetch and install dependencies for you, it’s fairly simple to use and doesn’t require the user to copy files around their system. For example to install Zen::Koan open a terminal and type:

    cpan Zen::Koan

    If you you’re using the Perl which ships with Ubuntu you will need to use sudo. On this topic I’d suggest not using the system Perl, as Ubuntu uses it for various systemy bits and bobs. You can Simply download the source and build it with a prefix /home/username/perl. See the Installation note in the README for details.

    Regarding packaging modules. Well you could simply pick one from CPAN and copy the layout. See also perlnewmod (which you can access via the command line using perldoc perlnewmod) and Creating and Distributing Modules.

    Should you need help with anything mentioned above, or have any further Perl questions consider posting over at perlmonks where people are always happy to help.

  8. bodhi.zazen says:


    CPAN looks interesting. I will review any suggestions any of the perl masters throw my way as honestly this is my first perl endeavor (so I am sure there are likely better methods).

  9. tenach says:

    You are quite welcome! I really enjoyed the koans and thought that I might as well make use of the HTML output!

    I have been poking around the code (first time looking into Perl) to see exactly what’s going on, and have been building a PHP class that will interface with it.

  10. bodhi.zazen says:

    @zengargoyle : Wow, just wow.

    Thank you for taking the time and interest in looking at all that code. Your modifications are very nice, but beyond what I could have done.

    It looks fantastic and I am looking at the modifications you made and learning a ton about perl.

    My question would be about packaging the new code, I could never claim to have written those modifications.

    I will send you an email.

  11. marto says:

    Cool, remember a CPAN distribution can be installed on any platform which has Perl. Providing this in addition to a .deb package gives you a wider audience.

  12. Thank you! It works flawlessly!

  13. bodhi.zazen says:

    You are most welcome, glad you liked it.

  14. Sean says:

    Love the Koans! Much thanks!

  15. Ubuntu Dharma!

    sudo apt-get install display-dhammapada

    Hi bodi.zazen!

    Like your combo linux/Buddhist site. Truth gets an upgrade.

    I’m going to make something like you’re doing on this blog. A mouse in the kitchen got me out of bed, around 4:30 this morning. Making noises, eating my chocolate and granola. But now I’m happy enjoying a living Buddha:


    Found your place by looking for an irc chat tutorial. The Dharma’s gotta go mobile. the terminal program is so 70s! Of course, I’m going back in tech time using irc… I’m interested in updating web and mobile devices with spiritual Teachings.

    Michael Harings

  16. bodhi.zazen says:

    @Michael Harings – Thanks for your comments, great link. come on over to #ubuntuforums on freenode once you find your way.

  17. Joseph Mills says:

    I have got the ppa up and running

    sudo add-apt-repository ppa:josephjamesmills/koan
    sudo apt-get update
    sudo apt-get install zen-koans

    btw it is addictive

  18. bodhi.zazen says:

    @Joseph Mills Thank you for packaging this.

  19. Eguzki says:

    ‘The perfect man has no self, the spirit-endowed man no achievements, the sage no reputation.’
    > Zhuang Zi

Leave a Reply

Your email address will not be published. Required fields are marked *