A quick guide to customize recipes
1.Intro
An excellent starting point to learn how to use recipes and create your own is the users' manual page which provides a couple of examples on how to customise the fetching of information from the BBC website and details the code which requires authentication with the New York Times.
This guide is aimed to users of any level who want to understand in more details how to customise recipes and make the best of the power of Calibre. If you are an advanced user and have already looked at the users' manual page, you might want to skip to the advanced customization tips.
2.Useful tools and info before you start
Before you start, you need to be aware that a basic understanding of HTML and CSS is required if you want to customise the fetch process. Calibre takes the HTML from the feeds URL and the recipe provides the functions to extract certain parts and collate them into an ebook in the different formats.
To edit a recipe you can use a simple text editor or a python editor (useful if you want to do more complicated things and like the colour-coded syntax).
To study the source code of an article, you could open it and paste into your favorite wHTML editor, but this can become tedious. Firebug is a free FireFox extension. It allows you to visually detect the document structure from within the browser (and a lot more). Alternatively, Google's Chrome browser (also free) has a built-in tool for this. Right-click on any element, choose 'Inspect' and a window pops up that lets you view structure of the document.
Be aware however that both these tools show the structure after the source has been parsed by the engine (all tables, for instance, have a <tbody/> tag, even if that tag was not present in the source). Modern browsers go out of their way to correct bad HTML markup, but calibre's parser may not be able to do the same. So, if you ever have trouble locating an element that is visible in an Inspector, examine the source.
Other useful FireFox extensions are Live HTTP Headers and Tamper Data. Both let you view the Request and Response Headers which is very handy if you need to figure out the exact communication between server and client. In addition, Tamper Data lets you add, delete or modify headers. With Web Developer you can delete session cookies, disable cookies, view form information, outline elements and a lot more.
To be able to test your recipes before using them in Calibre, you also need to have the command line interface enabled. You can use the custom recipes directly from the Calibre GUI, but it will be more complicated to detect errors and problems.
Where are the recipes?
There are two ways of getting the code for recipes.
- Open a recipe file, edit the code to suit and save the recipe file as a new recipe
- Using the GUI, add a Custom recipe by editing an existing one.
If you go for the first method, here is where you can find the recipes
- In Windows all the built-in recipes are located in the Calibre installation folder \resources\recipes\
- in OSX, right-click on the Calibre application in the Finder, select "Show Package Contents", and navigate to Contents/Resources?/resources/recipes
- in Linux ...
NOTE: you are strongly advised NOT to edit the built-in recipes directly from the recipes folder!
The second method is the recommended one and here is how you go about it.
- In the main window of calibre click the little arrow next to the "Fetch News" button and then click on "Add a custom news source".
- A new window opens up and on the bottom left corner click on "Customize builtin recipe".
- Now a little window opens up with a drop down box where you can pick the recipe of the news scource you wish to customize.
- Once you have chosen a particular news source it should appear in the list on the left column of the window.
- Select it in the left column and the recipe will appear on the right column of the window.
