Tag: Kindle

RFC2629 tools

Now that I have a java build that is redistributable, I can finally release the code source of the two tools I wrote to convert I-Ds and RFCs to a format that can be used on a Kindle. The Debian package containing this two tools is named “rfc2629-tools” and can be found at the usual place. In addition to this two tools, I also put in this package an additional tool that I use to process my RFC2629 XML sources.

Some quick explanation for the people new to the IETF process. All IETF documents, standards and others, are published as RFC (which is no longer an acronym) which are immutable documents. Before been published as RFC, documents are published as Internet-Drafts (I-D). The canonical form of RFCs and I-Ds is a line printer-ready format that is often called text format. There is other formats possible like PDF or HTML, but only the text format must be used as reference. Writing a well-formed text I-D or RFC is difficult, so authors generally write it in another format, then use a conversion tool to generate the text, PDF or HTML file. Some people use Winword, other use nroff but the most interesting format is an XML application defined in RFC 2629. There is available tools to convert an RFC 2629 source to text, PDF, nroff and HTML, but nothing for the Kindle platform.

One of the tools in the rfc2629-tools package takes as input a RFC 2629 source and generate an intermediary file that can then be processed to create a .mobi file that can be loaded in a Kindle. Here’s the command lines to do this:

$ xml2mobi draft-ietf-behave-turn-uri-09.xml
$ kindlegen draft-ietf-behave-turn-uri-09.htm

Note that the xml2mobi program is very much a work in progress, as it is incomplete and really need more work to be able to process with any RFC2629 source. I released the code source because I do not have much time currently for this, so anybody interested can work on a fork. For example, the file generated is named from the content of the docName attribute in the rfc element in the input file.
The kindlegen program can be found on Amazon Web site.

The IETF Secretariat archives the RFC 2629 source if the author provides it when uploading the text file but few people do this so another solution is needed to be able to read I-Ds and RFCs that are only available in text form. This is what the text2kindle program do:

$ txt2kindle draft-ietf-behave-turn-uri-09.txt

This command creates a file named draft-ietf-behave-turn-uri-09.zip that can be installed directly in a directory named /pictures on the Kindle 2. On the Kindle 1, the file must be unzipped in the /pictures directory.
Note that the document is displayed as a series of pictures so you cannot annotate them.

Even if the RFC2629 source of an I-D is available on the IETF web site, that does not mean that you will be able to generate a mobi file for your Kindle that is identical in content to the canonical version. The first reason is that the full date is generally not set, which means that running a conversion tool on this source will generate a document with the current date instead of the date that is used in the canonical document. The second reason is that people generally uses the <?rfc include> statement to insert references. The problem with this is that the text included will change when a new version of the I-D referenced will released, so again it is not possible to generate a content identical to the canonical document. The solution to this problem is to generate an RFC2629 document that always contains a complete date and where all references are already included. With this what the third tool in the package provides:

$ rfc2629 draft-ietf-behave-turn-uri.xml

This command will copy the content of the file passed as input with the following transformations:

  • The destination file is named from the content of the docuName attribute (this helps when the document is stored in a source control system).

  • The date in the destination file is filled with the current date.

  • All the xinclude statements are replaced by their content

  • All comments are removed.

The resulting XML file can be uploaded to the IETF site with a guarantee that other formats can be generated from this file as identical as the files generated by the author.

The same script also implements a feature that permit to rename a reference. A reference to an I-D generally looks like this is the result text:

The TURN specification [I-D.ietf-behave-turn] defines a process for a

The map element can be used to change the name displayed:

<map anchor="TURN">
  <xi:include xi:href="http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-behave-turn.xml" />
</map>

Which, after been processed by the script and xml2rfc will generate this instead:

The TURN specification [TURN] defines a process for a TURN client to

The last feature of this script (for now) was added when I tried to release two I-Ds at the same time, with each I-D containing a reference to the other. Because the text that will be included is generated after the upload to the IETF, there was no way to automatically use the correct reference. What the script do is to generate a reference file automatically in /tmp for all the files processed. It is then easy to include the correctly generated reference is the document. For example draft-ietf-behave-turn-uri.xml and draft-petithuguenin-behave-turn-uri-bis.xml have a reference on each other. So the first step is to change the reference inside draft-ietf-behave-turn-uri.xml like this:

<xi:include xi:href="/tmp/reference.I-D.petithuguenin-behave-turn-uri-bis.xml" />

and to change the reference inside draft-petithuguenin-behave-turn-uri-bis.xml like this:

<xi:include xi:href="/tmp/reference.I-D.ietf-behave-turn-uri.xml" />

Then running the script on the two XML files at the same time generates the correct XML file, ready to be uploaded to the IETF:

$ rfc2629 ../src/share/docs/draft-ietf-behave-turn-uri.xml ../src/share/docs/draft-petithuguenin-behave-turn-uri-bis.xml

Vacation readings

Vacation is more or less the only time I can read books. My Kindle 2 made it easy to carry them around and read them on planes, trains and metro during my last vacations in France:

  • Absinthe & Flamethrowers: Projects and Ruminations on the Art of Living Dangerously (William Gurstelle):

    A short and interesting book, but I would not put drinking absinthe in the list of dangerous things – well at least in my opinion it is way less dangerous than eating fast food regularly. I will probably write a bit more about the ideas on this book, as there is some that are related to something I will spend most of my time for the next year.

  • Daemon (Daniel Suarez):

    An excellent novel that is, a the difference of most novels about technology, completely realistic. I cannot wait for the sequel.

  • Thomas Jefferson (R. B. Bernstein):

    Thomas Jefferson is probably, with Benjamin Franklin, the most interesting of the Founder Fathers. This biography was so interesting that I found it way too short and I will try to find something that would go deeper in the life of this extraordinary person.

  • Declare (Tim Powers):

    There is no such thing as a bad Tim Powers book and there is no such thing as an easy to read Tim Powers book. My favorite is still Last Call but Declare was really captivating after I managed to read pass the first one hundred pages.

  • Fugitives and Refugees: A Walk in Portland, Oregon (Chuck Palahniuk):

    Well, I read everything from Palahniuk (*cough* Haunted *cough*), so I had to read this one, even if it is not a novel but a travel guide. As always, extremely entertaining.

Internet-Drafts for Kindle (2)

Yesterday I explained about my efforts to convert Internet-Drafts to a format that is usable on the Amazon Kindle. The solution described is certainly fine for the long-term, but does not help for the IETF meeting in 10 days. So for the short-term, I developed another Java program that takes an Internet-Draft or an RFC in text form and convert it to a series of images that can be displayed on a Kindle. All the nice features of the Kindle like reflow, dictionary, TOC, links, bookmarks, annotations, etc…, do not work with this, but that’s better than printing – and carrying around – 500+ pages. The program is available here:

http://ietf.implementers.org/id2kindle.jar

And can be used like this:

java -jar id2kindle.jar rfc3261.txt rfc3261.zip

The .zip file must be installed directly in a directory named /pictures on the Kindle 2. On the Kindle 1, the file must be unzipped in the /pictures directory.

On the Home menu of the Kindle use Alt-Z to rescan the flash memory and the new document should be selectable. Press J to switch the full page mode.

Formatting Internet-Drafts for the Amazon Kindle

The 74th IETF meeting is coming fast and it is time to start reading the latest version of all the Internet-Drafts relevant to the sessions one plan to attend. I counted 70 documents in my case, and that’s a lot of reading. Printing all this documents is bad for the environment but it is so far the easier way to manage this task especially because it is easy to annotate them directly with a pen. Reading on a laptop is not as convenient and does not make annotations easy.

I was thinking since few IETF meetings that my Kindle would be ideal for this task. It is small enough to be easily carried around, does not need to be recharged as often as a laptop, and permits to annotate documents. Unfortunately the text formatting of an Internet-Draft does not look very good on a Kindle, as it is optimized for text console with 80 columns.

So I wrote a converter that take in input a RFC 2629-formatted Internet-Draft and convert it to a .mobi document that displays nicely on a Kindle. I would have been happy to write an XSLT script for this task but unfortunately the Kindle cannot display correctly tables or some special formatting needed by IETF documents, so I used Java to generate the tables as images. The code is not very smart yet, but I was able to convert my 3 current I-Ds to .mobi files and they can be downloaded here:

http://ietf.implementers.org/

This will not solve the problem of reading all this drafts soon because very few authors upload the RFC 2629 version of their draft to the IETF website, but I hope that this will encourage people to start doing it.