KindleGen utility

First of all you need to download KindleGen utility and unpack it to whatever folder you want. I put it to my Dropbox folder to be able to run it on all my computers and then I set an alias for kindlegen.exe file.

PS C:\> Set-Alias -Name kg -Value Dropbox:\Utilities\KindleGen\kindlegen.exe

Amazon provides two samples so can check folders Sample and MultimediaSample for general info.

Starting point – CHM file

As a source I used PowerShell help file located in C:\WINDOWS\help\WindowsPowerShellHelp.chm. CHM is “just” a bunch of HTML pages compiled together. You can see it’s structure for example via 7-Zip.

For us are important those files/folders:

• html folder – contains all topics from CHM file – one HTML page per topic.
• local folder – contains “support” files – pictures used in help, CSS file and JS file.
• PowerShell_GPSplusC.hhc – table of contents for CHM file.

You can grab all of those to your drive by using hh.exe utility.

PS C:\> Get-Command hh.exe | fl
Name            : hh.exe
CommandType     : Application
Definition      : C:\WINDOWS\hh.exe
Extension       : .exe
Path            : C:\WINDOWS\hh.exe
FileVersionInfo : File:             C:\WINDOWS\hh.exe
InternalName:     HH 1.41
OriginalFilename: HH.exe
FileVersion:      5.2.3790.2453 (srv03_sp1_qfe.050525-1536)
FileDescription:  MicrosoftR HTML Help Executable
Product:          HTML Help
ProductVersion:   5.2.3790.2453
Debug:            False
Patched:          False
PreRelease:       False
PrivateBuild:     False
SpecialBuild:     False
Language:         English (United States)

Simply run this command:

PS C:\> hh.exe –decompile hlp c:\windows\help\WindowsPowerShellHelp.chm

and you will see files/folders mentioned above in new hlp folder. You can then check it’s contents to be familiar with the structure.

Let’s build the structure

Now you need to create four files.

1. .OPF file – Open Packaging Format file is XML based file and defines “structure” of your final book. More can be found is OPF specification. In Sample folder of KindleGen installation you can check Guide.opf file as it contains also comments to all elements. I used it as a starting point also. Biggest advantage is that it contains information about mandatory elements of the file. Most important elements are: <manifest> – contains list of all files you’ll include in final book. <spine> – ordered (in a way of linear reading) list of HTML files. <metadata> – some general info about final book. As I included cover, it has to be mentioned here.
2. .NCX file – Navigation Control file for XML is table of contents. In Sample folder you’ll see some nesting of elements but I found that for my case I was OK with just two levels – chapter and section. On my Kindle I don’t care about five levels as it’s in source CHM file.
3. toc.html – Table of contents as it will be shown visually on Kindle. I just used simple <ul> tags to show really basic outline. You can see the picture of my TOC below.
4. about.html – some short info about the book.

Two mentioned HTML files are not mandatory but I found useful to include them.

As a resume let’s see what we have now.

Dropbox:\PowerShell\Scripts\Help2Kindle\PowerShellP> ls

Mode                LastWriteTime     Length Name
—-                ————-     —— —-
d—-            4.1.11  10:27 PM            html
d—-            3.1.11   8:19 PM            local
-a—            4.1.11  11:57 AM        810 about.html
-a—            5.1.11   4:41 PM       6616 cover.gif
-a—            4.1.11   5:19 PM     109400 PowerShellP.ncx
-a—            5.1.11   4:49 PM      94708 PowerShellP.opf
-a—            4.1.11   4:58 PM      44067 toc.html

We can go to generate our final MOBI file.

Dropbox:\PowerShell\Scripts\Help2Kindle\PowerShellP> kg .\PowerShellP.opf
***********************************************
* Amazon.com kindlegen(Windows) V1.1 build 99 *
* A command line e-book compiler              *
* Copyright Amazon.com 2010                   *
***********************************************
opt version: try to minimize (default)
Info(prcgen): Added metadata dc:Title        “PowerShell Help”
Info(prcgen): Added metadata dc:Date         “2011-01-05″
Info(prcgen): Added metadata dc:Creator      “@makovec”
Info(prcgen): Added metadata dc:Publisher    “PowerShell.cz”
Info(prcgen): Added metadata dc:Subject      “PowerShell Help”
Info(prcgen): Added metadata dc:Description  “Help files provided with PowerShell.”
Info(prcgen): Parsing files  0000457
Info(prcgen): Resolving hyperlinks
Info(prcgen): Resolving start reading location
Info(prcgen): Added metadata Start reading   “65BE”
Info(prcgen): Building table of content     URL: Dropbox:\PowerShell\Scripts\Help2Kindle\PowerShellP\PowerShellP.ncx
Info(prcgen): Computing UNICODE ranges used in the book
Info(prcgen): Found UNICODE range: Basic Latin [20..7E]
Info(prcgen): Found UNICODE range: Letter-like Symbols [2100..214F]
Info(prcgen): Found UNICODE range: General Punctuation – Windows 1252 [2026..2026]
Info(prcgen): Found UNICODE range: Latin-1 Supplement [A0..FF]
Info(prcgen): Building MOBI file, record count:   0001927
Info(prcgen): Compiling HTML Parser restart information
Info(prcgen): Final stats – text compressed to (in % of original size):  038.49%
Info(prcgen): The document identifier is: “PowerShell_Help”
Info(prcgen): The file format version is V6
Info(prcgen): Saving MOBI file
Info(prcgen): MOBI File successfully generated!

And the file is there:

Dropbox:\PowerShell\Scripts\Help2Kindle\PowerShellP> ls *.mobi

Mode                LastWriteTime     Length Name
—-                ————-     —— —-
-a—            6.1.11  11:59 PM    4598551 PowerShellP.mobi

Some notes

• I manually modified some HTML files. There were missing some tag’s parameters and KindleGen generated warning. It was not critical but I wanted nice output just with info messages.
• I found out that (in my opinion) is not necessary to create chapters/sections with deep nesting. Maybe – as the only exception – is the toc.html file itself where it should be useful to see the structure. But I decided that it’s not that important for me.
• You need to put ordered file names into <spin> tag in OPF file. Otherwise you content will be sorted by file name which is not so useful.
• Use Sample folder as a starting point. It’s pretty well described.
• Cover image size should be 800×600.

That’s enough of theory for now. Today we didn’t play with PowerShell so much so next time I’ll dedicate whole post to techniques I used during whole process (generating of files, TOC order, etc.)

Amazon provides command line tool named KindleGen and I recommend you to download it together with Kindle Previewer (both located at Amazon Kindle’s Publishing Program page). With KindleGen you’ll receive also two samples so you can find how it works.

As a source I used CHM file provided with PowerShell (you can access it from ISE by pressing F1 key).

I simply extracted HTML files from that file (by running hh.exe –decompile hlp c:\windows\help\WindowsPowerShellHelp.chm) and then process those files with KindleGen. As a result I received nice MOBI file You can download the result from this location.

As this was really funny work and whole process of the file creation is not described anywhere (AFAIK) I plan some blog posts in the near future to show how to work with KindleGen itself and also to show how I used PowerShell to help me with some conversion/copy&pasting/generating XHTML.

Please note that my influence to this book was only the conversion from CHM to MOBI. All the texts inside were created by people from PowerShell team (except to Preface – I added it just for clarification) and all kudos needs to be send to Redmond.