Wednesday, December 22, 2010

Comic: Public Key Cryptography in a fairy tale!


The comic shown above shows a PKC scenario of a commonly known fairly tale "The Frog Prince". This was done by a group of ten people including me. Try and see whether you can understand it!! :) (click on the image to see it in original size (obviously)!)

HINT: This involves a Witch, a princess, and a frog (prince), and this shows the encryption scheme of PKC.

This comic was done as a requirement for the "Computer Security" module in my department, Dept. of Computer Science & Engineering, University of Moratuwa.

Sunday, December 12, 2010

How to Use docbkx-tools as Maven DocBook plugin

When it comes to documentation of open source projects, DocBook is the favorite choice among many developers. As you all know, DocBook provides a comprehensive XML schema to document your project, which you can transform to any format such as html, pdf, webhelp etc. Here, I'm going to show you how to integrate DocBook in to your Maven project via docbkx-tools. This docbkx-maven-plugin makes docbook integration to Apache Maven much easier.

Reference DocBook XSLs from your customization layer
Probably you are not planning to use DocBook standard stylesheets alone, but have a little more customization to it. For that, you have to create a new customization layer, and import the standard docbook.xsl stylesheet. 
It's a little tricky how it's done in this plugin. You should give a symbolic reference rather than an actual file location when importing the stylesheets. You should use <xsl:import href="urn:docbkx:stylesheet/docbook.xsl" /> to give the symbolic reference.
What "urn:docbkx:stylesheet" refers will depend on what customization (html, xhtml, etc.) you want to use. If you want to use xhtml/chunk.xsl customization, first specify it in your XSL by     <xsl:import href="urn:docbkx:stylesheet/chunk.xsl"/> and then, in your POM, specify the <xhtmlCustomization>. Further details are explained below.

Integrating dockbkx-tools to Maven projects
OK, now let's see how to integrate this nice Docbook plugin to your maven project.
  • First, you have to add the docbook plugin to your parent POM file pom.xml. The docbook xml documentation should be on path trunk/src/docbkx.
    <build>
        <plugins>
            <plugin>
                <groupId>com.agilejava.docbkx</groupId>
                <artifactId>docbkx-maven-plugin</artifactId>
                <version>2.0.11</version>
                <dependencies>
                    <dependency>
                        <groupId>org.docbook</groupId>
                        <artifactId>docbook-xml</artifactId>
                        <version>4.4</version>
                        <scope>runtime</scope>
                    </dependency>
                </dependencies>
                <configuration>
                    .......
                </configuration>
                <executions>
                    ......
                </executions>
            </plugin>
        </plugins>
    </build>

As you can see, the plugin depends on the docbook-xml artifact. After adding this structure to your POM, you just have to customize it according to your needs.
  • Then, you have to set the configurations in <configuration> tag. In that, you should menion the xsl customization file, if you have a customized docbook XSLs. Else, you can just use the generic XSLs provided by DocBook. At this point, the docbkx's version is 2.0.11 and it uses DocBook-XSL-NS 1.75.2  version. Mind that it's the namespace version, so make sure you make your customized version with NS too. Else, you may encounter errors which could be hard to track. For the customizations, for html, use <htmlCustomization> tag to mention the customizations. For PDF, it's <foCustomization>. and <xhtmlCustomization> for, obviously, xhtml. A sample is below. You may put configurations under <executions> too, if you wish.
  • The new customization to the DocBook-XSL family, DocBook WebHelp, is not yet included on this version, but the people are working on it to make it available as soon as possible. I'm eagerly waiting for it, mainly because I contributed to it a lot; plus it's a nice customization which you can actually put in the web for your audience to see.
        <configuration>
            <foCustomization>src/docbkx/xsl/fo.xsl</foCustomization>
            <xhtmlCustomization>src/docbkx/xsl/xhtml.xsl</xhtmlCustomization>
        </configuration>                
  • Now it's to set the 'executions' you need to run. Executions specify what goals you run, copy CSS/JavaScript files you might have etc. A sample execution code is given below.

        <executions>
            <execution>
                <id>userguide</id>
                <phase>pre-site</phase>
                <goals>
                    <goal>generate-xhtml</goal>
                </goals>
                <configuration>
                    <includes>userguide.xml</includes>
                    <targetDirectory>target/site/userguide</targetDirectory>
                    <chunkedOutput>true</chunkedOutput>
                    <xhtmlCustomization>src/docbkx/xsl/userguide.xsl</xhtmlCustomization>
                    <postProcess>
                        <copy todir="target/site/userguide/">
                            <fileset dir="src/docbkx/template">
                            </fileset>
                        </copy>
                    </postProcess>
                </configuration>
            </execution>
        </executions>  

What happens there? First, it specifies the phase 'pre-site', which tells to Maven that, this execution should be run first when invoking 'mvn site' command. 
    • <goal> - is set to generate-xhtml which will generate a xhtml output. Other options are generate-html and generate-pdf.
    • <includes> - This tag specifies which document should be processed. The path was trunk/src/docbkx/userguide.xml.
    • <configuration> - Then it comes to the configuration part. Most of it are self understandable. As you can see I've set the XSL customization I wish to use there. You can put it anywhere, both worked fine for me. 
      • <chunkedOutput> will generate set of html files rather than one BIG html file which are broken down based on the tags <chapter>, <section> etc. in your docbook xml file.
      • I copied all the CSS/JavaScript/Images to target folder by using the <postProcess> tag. It's easier. The source files were at src/docbkx/template.
  • You may write another <execution> to generate the PDF output. The whole code I used is given below.

        <build>
            <plugins>
                <plugin>
                    <groupId>com.agilejava.docbkx</groupId>
                    <artifactId>docbkx-maven-plugin</artifactId>
                    <version>2.0.11</version>
                    <dependencies>
                        <dependency>
                            <groupId>org.docbook</groupId>
                            <artifactId>docbook-xml</artifactId>
                            <version>4.4</version>
                            <scope>runtime</scope>
                        </dependency>
                    </dependencies>
                    <configuration>
                        <foCustomization>src/docbkx/xsl/fo.xsl</foCustomization>
                    </configuration>
                    <executions>
                        <execution>
                            <id>userguide</id>
                            <phase>pre-site</phase>
                            <goals>
                                <goal>generate-xhtml</goal>
                            </goals>
                            <configuration>
                                <includes>userguide.xml</includes>
                                <targetDirectory>target/site/userguide</targetDirectory>
                                <chunkedOutput>true</chunkedOutput>
                                <xhtmlCustomization>src/docbkx/xsl/userguide.xsl</xhtmlCustomization>
                                <postProcess>
                                    <copy todir="target/site/userguide/">
                                        <fileset dir="src/docbkx/template">
                                        </fileset>
                                    </copy>
                                </postProcess>
                            </configuration>
                        </execution>


                        <execution>
                            <id>userguide-pdf</id>
                            <goals>
                                <goal>generate-pdf</goal>
                            </goals>
                            <phase>compile</phase>
                            <configuration>
                                <includes>userguide.xml</includes>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
YBQQQSEANSZ5

Thursday, December 9, 2010

Heard of 2D bar codes? It's awesome!

QR code for the URL http://blog.kasunbg.org
While crawling through web, I found this awesome technique called QR codes. It is short for "Quick Response Code", a 2D bar code system, which first introduced in Japan way back in time (1994 precisely, says wikipedia :) ). These codes could be the future, where every magazines and papers carry out these to give some important details or the URL of it to their readers. These codes can be easily read by an Apple iPhone, Android... or basically from any phone with a camera and a QR reader app!

So, what is it exactly?
You might be wondering is it a way to communicate secret message? or just another bar code to be used in your grocery store. Well, it's not a secret cipher where you have to know the key to decode it. Well then, what's the use of it? Suppose you are this big guy/gal who has a business card for yourself. How much time will customers of yours will keep your card in their pocket when you give it to them; a month? say two months max, then surely they might lose it somewhere or may be end up in laundry! But if you print your QR code in it, they can scan it, and store your info as a 'contact' in their phone. Problem solved! One other occasion is, you can show your web sites URL from that image, and interested people can quickly scan it and go to your site. For instance, the above QR image opens this weblog. QR codes are expected to be a popular technology especially between smartphone users.

How to create them

I used QR-Code Generator to create them. There are plenty of free sites available for creating these QR codes. From there, you can create an image out of a URL, which when detected, will redirect you to that URL in your mobile browser. Else, you can simply store a text you like. For example, here's my business card. Decode it and see ;)


Here's a video of using QR codes in business cards.