El Tramo | Writing

Beautiful (XMPP) Testing

2009-11-02T00:00:00+01:00

O’Reilly recently released the book Beautiful Testing, a collection of essays about testing and QA in general. As I mentioned earlier, I wrote an article in that book on (unit) testing XMPP protocols, using Swift as a motivating example. Since the book’s scope may (oddly enough) not always be as interesting for developers in general, I released my article under a Creative Commons Attribution license (thanks to the good folks from O’Reilly for encouraging us to do this), which you can find here (or directly from my Git repository). The original excerpt from the book (including the index, list of biographies, and all the fancy artwork) is also available for download under the same license. I of course encourage you to buy either the PDF or dead tree version of the book, as all the proceeds of the book go to charity.

“XMPP: The Definitive Guide” Code Examples

2009-07-13T00:00:00+02:00

Although the primary focus of XMPP: The Definitive Guide is explaning the XMPP protocol and all its extensions through text and illustrations, we also included a few Python code examples to help people get started with implementing their own ideas. In fact, we devoted a whole chapter to building an XMPP application, starting out with a simple bot implementation, but gradually extending the application into a full server component. For people who want to try this out for themselves, we’re releasing the source code of all code examples, including a simple echo bot, and different variants of the CheshiR microblogging platform XMPP interface. All examples are built using the lightweight SleekXMPP Python XMPP library. In fact, SleekXMPP is so lightweight that we included a version in the source bundle, making it even easier to get started implementing your own bots and components. Do bear in mind that these examples only serve illustrative purposes for the book, so don’t expect very robust code. Although making this code fail-safe is not really our primary goal (since that would involve a lot of code that would only distract the reader), we do welcome bug reports or fixes. The code examples are available as a source package, or directly from the Git repository (mirrored on GitHub). We will soon put a link to the package on the book’s webpage.

Integrating DocBook with WordPress

2009-06-27T00:00:00+02:00

I added a DocBook XSL customization layer to my DocBook Kit that outputs an HTML/PHP version of the document that automatically integrates with a WordPress blog. The stylesheet also (optionally) adds a link to the downloadable PDF of the document. An example document integrating with this blog can be seen here. The custom stylesheet is based on the standard DocBook XSL XHTML stylesheet. However, instead of inserting an HTML header, it inserts PHP calls to include the WordPress headers and footers. The only tricky part of this is to tell WordPress what the title of the resulting page should be. I hacked this in by creating a class with the bare minimum fields required by wp_title() (which is used by WordPress to print the title of the document). The resulting template looks like this:

<?php
  require('../wordpress/wp-blog-header.php');
  class MyPost { var $post_title = "My Title"; }
  $wp_query->is_home = false;
  $wp_query->is_single = true;
  $wp_query->queried_object = new MyPost();
  get_header();
?>
<div id="content" class="narrowcolumn" role="main">
  ...
</div>
<?php
  get_sidebar();
  get_footer();
?>

The DocBook kit is available from my Git repository (or on GitHub, or as a ZIP file). More information about the kit can be found here.

“Beautiful Testing” XMPP Chapter

2009-05-03T00:00:00+02:00

Adam Goucher and Tim Riley (Director of QA at Mozilla) announced a few months ago that they are putting together a Beautiful Testing book for O’Reilly. I took the opportunity to write a chapter about testing in the context of XMPP (more specifically, about testing protocol implementations in Swift), and just submitted the final draft for technical review. The book is expected to be released this August. Although there are many types of testing being done in the XMPP world, the chapter focuses on the beauty of testing the functionality of XMPP protocol implementations. After a brief introduction on XMPP, it starts out with a description of unit testing simple IQ request/response protocols, and then gradually moves on to higher-level testing of more complex, multi-stage protocols such as session initialization. As you might expect from a developer like me, the chapter is quite heavy on the (C++) code, but I’m told it compensates for the rest of the book ;-) As with all other books in the O’Reilly “Beautiful” series (which started with Beautiful Code, but has since been followed up by Beautiful Architecture, Beautiful Teams, Beautiful Security, and Beautiful Data), all proceeds of the book go to charity, in this case “Nothing But Nets” (which provides mosquito netting to malaria infested areas of Africa). This means that I can plug this book as much as I want, and still have the feeling I’m actually doing a noble, unselfish thing. (contrary to when I casually mention that you can buy our book XMPP: The Definitive Guide at very sharp prices these days). Some time after the book’s release this summer, I will even make a free version of the chapter available here, so check back soon!

Kick-starting a DocBook Project

2009-04-29T00:00:00+02:00

When I started writing XMPP: The Definitive Guide, I switched from LaTeX to DocBook as my writing tool, mainly because DocBook was O’Reilly’s suggested format. After a few months of writing with DocBook, I started getting quite attached to the format: not only does it force you to separate presentation from content, the strict XML format allows you to easily write tools to transform and validate your document. For example, for the XMPP book, we had several short Python scripts that checked whether the stanzas used in the book were well-formed, whether all web URLs were valid, ... Today, I use DocBook for practically all of my documents. Because getting a DocBook environment up requires putting together quite a few pieces from different places, I created a “DocBook kit” to be able to start writing a new DocBook project without much hassle. Starting a DocBook project requires a few elementary tools to be installed:

The DocBook XML schemas. These are used to validate whether your document is a legal DocBook document.
The DocBook XSL stylesheets. These are used to transform your DocBook input file into other formats, such as HTML or XSL-FO (a format which can be converted to PDF)
XML and XSL processing tools. These tools take the schemas and stylesheets mentioned above, and apply them to your document to do the actual checking and transformation. I use xmllint and xsltproc (available out of the box on many platforms and distributions), but other tools can be used as well (e.g. Saxon or Xalan)
An XSL-FO processor, to transform the intermediate XSL-FO format generated by the stylesheets to PDF. I use the Free Apache FOP, but commercial tools such as RenderX XEP and AntennaHouse are very popular for this too.

Once you have all these tools, you need to tie them all together to be able to get from your DocBook file to your desired output format, such as PDF or HTML. Because this involves quite some boilerplate scripting, I created a DocBook kit to make this as light as possible. The DocBook kit comes with a Makefile, which you can use to do all the work for you. The kit also automatically downloads the DocBook XML schemas and XSL stylesheets, making it possible to start working on a DocBook project on a machine with only some basic tools (xmllint and xsltproc) installed. To use the kit, simply drop it in the directory of your project, and create a minimal Makefile such as the following one:

# The toplevel DocBook file of our project
DOCUMENT = MyDocument.xml

# Include the DocBook Kit's makefile rules
include docbook-kit/tools/Makefile.inc

This makes several make commands available, such as:

make, make pdf, make html, make txt: Creates an HTML, PDF, and/or TXT file of your document.
make check: Validates your document syntactically.
make check-spelling: Runs a spell checker on your document.
make package: Creates a flat DocBook file (i.e. one with all the parts included using XIncludes expanded), normalizes all figure names, and packages the result up into a tarball.

The makefile also tracks the dependencies of the document, making sure that your document is rebuilt whenever one of its dependencies (e.g. images, document parts included using XInclude) changes. Besides tools, the kit also provides a customization layer around the standard XSL stylesheets. These customizations change fonts, spacings, and other presentation parameters for the output document. You can use these as an example on how to make your DocBook document look the way you want. Detailed information on using and customizing the DocBook XSL stylesheets can be found in Bob Stayton’s DocBook XSL: The Complete Guide. The DocBook kit is available from my Git repository (or on GitHub, or as a ZIP file), and comes with an example of a simple project using the kit. More tools and features will be added in the future.

We have an animal

2009-02-08T00:00:00+01:00

O’Reilly just sent us the cover for our upcoming XMPP Book, and it seems we got the world’s smallest ungulate: the lesser mouse-deer. I haven’t seen one in real life before, am not sure I ever want to, but still: great! Have a look below to see what the cover of the book will look like when it hits the stores in 2 months.

Final revision of the XMPP book submitted

2009-02-03T00:00:00+01:00

After a few weeks of heavy labour and long nights, Peter, Kevin, and I just submitted the final revision of “XMPP: The Definitive Guide” to the folks at O’Reilly. All the feedback from our (thorough) reviewers has been processed, we added quite a few extra bits and clarifications (58 pages to be exact), polished the whole thing up, and went through the resulting manuscript with a fine toothed comb. We hope the people who will read this book will be as satisfied with the end result as we are. If all goes according to plan, the book should roll out of the presses in about 2 months. In the mean time, you can expect an update to the on-line rough cut version of the book in the next couple of days.

Rough cuts of XMPP book now available

2008-12-10T00:00:00+01:00

While Kevin, Peter, and I are working very hard to finish the first draft of our upcoming book ‘XMPP: The Definitive Guide’, O’Reilly has recently released early versions of most of the chapters of the book as Rough Cuts. People interested in learning about XMPP today can now get a preliminary version of the book, and get updates as the book progresses.

We're writing an XMPP book

2008-08-21T00:00:00+02:00

I'm excited to announce that Peter, Kevin, and I recently got the green light from O'Reilly to start writing a book about Jabber/XMPP. The book will be targeted at a diverse public: on one hand, people who want to get acquainted with XMPP and will get an introduction and a general overview of XMPP, its workings, and its possibilities. On the other hand, software engineers who want to integrate XMPP into their products will get a guide to implementing different use cases of XMPP through a series of different developer stories. The book is expected to be available in 2009, so start making some room on your bookshelf!

'The First 10 Prolog Programming Contests' available for downloading

2006-07-01T00:00:00+02:00

Exactly one year after we finished it, our book `The First 10 Prolog Programming Contests' is now freely downloadable. On the home page of the book, you will also find the source code of all solutions presented in the book. Below are some pictures of the 'deluxe' edition of the book, hand-made by my mom.