Generate a catalog using Calibre2Opds

Overview Installing Generating Publishing Using Troubleshooting

This section of the documentation discusses what is involved in generating a Calibre2Opds catalog.  In particular it discusses the many configuration options that are available to help you make the catalog look and operate the way that you prefer.

Note that although there are lots of configuration options available for your first use it would probably make sense to leave them at their default values wherever possible.

This section covers the following topics:



Preparing books for calibre2opds

Before you even attempt to use calibre2opds you must have first used Calibre to create an eBook library and added some books to it and set their metadata appropriately. The remainder of this section assumes that you have done that and that you have an eBook library under Calibre control for which you want to generate online catalogs in OPDS and/or HTML format.

The quality of your calibre2opds catalogs depends on the quality of the data you have stored about your books in the calibre library.   Most of the time you can simply run the calibre2opds programs against your calibre library and you will get the results you expect. However there are a few points to keep in mind:

  • Have desired format available
    This might seem obvious, but it is surprising how many people forget this! The calibre2opds software does not carry out any format conversion – it relies on you having already got the books into the calibre library in the format(s) that you intend to be able to download via a calibre2opds generated catalog.
  • Ensure metadata in ebook file updated
    This is a less obvious point that users frequently fall foul of because they are not aware of how calibre works under-the-covers. If in Calibre you add a book to the Calibre Library and then update the metadata about the book via the Calibre GUI, then the results are at that point ONLY stored in the Calibre metadata database – they are not written back to the actual ebook file. Most ebook reading software will extract the metadata from the ebook file for display on the reading device so you want this to match what you have set up in calibre.If you are not using calibre2opds then does not normally matter as in Calibre you would use the “Save to Disk” or “Send to Device” commands to get your book out of the Calibre library ready to be used, and these commands update the embedded metadata as part of the process.If you are using a calibre2opds generated catalog, then you have bypassed the use of the “Save to Disk” or “Send to Device” commands so if you want your metadata to be displayed correctly in your ereader, then you have to take alternative action to get the metadata into the physical ebook file. There are several ways to do this:

    • The most generic way is to run a Calibre “Convert Book” command on the book. If necessary you can simply convert the book to the same format (e.g. Mobi to Mobi as this will insert the updated metadata into the ebook file over-writing the original copy.
    • For ePub format files you have some additional options:
      • You can use the “Modify ePub” plugin that is available as an optional extra for use within Calibre.  This is probably the best way to go as it provides the maximum amount of fine-grained control.
      • You can use the “Reprocess ePub” option on the main calibre2opds configuration tab to make sure that the ePub files cover and metadata match the calibre metadata database.

Running calibre2opds

There are two ways of running the calibre2opds program:

  • GUI front-end:
    Most users will probably use this method.   This gives you a graphical front-end where you can see and set all the calibre2opds configuration options.   When you start generation you get feedback on progress.
  • Command Line Interface:
    This is appropriate for batch or repeating jobs. Note that in this mode you can only generate a new catalog according to the last set of parameters set via the GUI front-end.

Normally the Calibre2opds GUI is started by using the shortcut that is installed as part of the installation process.  However if for any reason the shortcuts are not available then you might like to know that the shortcuts are equivalent to running the following commands:

Windows:    javaw -jar ‘OpdsOutput-2.2-SNAPSHOT.jar’
Linux/Mac: java -jar ‘OpdsOutput-2.2-SNAPSHOT.jar’
where the name of the .jar file is the one corresponding to the current release.

The following screenshots show calibre2opds running on a windows 7 system. On a different version of Windows or on Linux or macOS the details may differ slightly although the fundamentals will stay the same.

When you launch calibre2opds then it will display a screen of that looks like the following:

Calibre2opds uses a tabbed dialog to display parameter options which helps keep the screen space occupied by the dialog down. This is to help those who use systems with limited screen resolution.

If you switch between the different modes then the options you can set may change slightly, and in addition certain options may be forced to specific values to suit the mode that you have selected. The screen-shots are chosen to show the maximum number of options available so do not worry if not all the options shown in the screenshot are available in the mode you are trying to use.

You can bring up a tooltip about each option by clicking on the label associated with that option. For more information on specific options look at the more detailed descriptions about the options following each screenshot in the rest of this section
.

Menu Options

Calibre2opds has a small number of options that are set by the menus at the top of the screen.

File Menu

Calibre2Opds FileMenu.jpg

These options are equivalen to the “Save”, “Generate Catalogs” and “Exit” buttons on the main screen.  It is likely that the average user will simply use the buttons and not bother with these menu options.

Profile Menu

A profile is a complete set of calibre2opds configuration settings that can be stored under a friendly name and then re-instated at a later date. Many users will only have one profile, and for such users this feature can be ignored. Others may have a number of different sets of settings for which they want to generate catalogs and this allows for an easy way to quickly re-instate the settings.

Calibre2Opds ProfilesMenu.jpg

Initially on the default profile would be shown, but as the user specifies new ones these will be listed below the default profile with the currently active one ticked.

Selecting the New profile option will result in the following dialog:

Calibre2Opds NewProfile.jpg

After you have specifed a name, the new profile will be now be shown on the Profile menu. The settings will initally be set to the current settings.

If you select the Manage profiles option then you will be shown the following dialog:

Calibre2Opds ManageProfiles.jpg

Any profiles you have set up will be displayed, and you can optionally rename them or delete them. If you do not want to do either then simply close the dialog.

Tools Menu

Calibre2Opds ToolsMenu.jpg

When you change metadata in Calibre the underlying ebook files are not actually updated with the new metadata unless you run a conversion on them. This means you could potentially download a file via a calibre2opds generated catalog where the metdata embedded in the file did not match the metadata stored in the Calibre database. When Calibre loads ebook files onto a reading device this is not an issue as calibre updates the metadata in the copy it loads onto the reader.

Using this option will cause calibre2opds to go through every epub file in the Calibre library and update the embedded metadata to match what is stored in the Calibre metadata database. This ensures that a file downloaded via a calibre2opds generated catalog has embedded metadata that matches the details displayed in the catalog.

Calibre2Opds ToolsSelect.jpg

The option to remove CSS is very specialist. It is used to remove the stylesheets from an epub file. This is done by changing the name of the stylesheet stored in the epub to add .bak to the name. The file is renamed rather than removed so that if you later want the stylesheet back again it is possible to open the epub file and rename it back to the original name. Using this option only makes sense if you ahve books that are very badly formatted. 
NOTE. it is likely that this option will be removed in a future calibre2opds release as it is very rare you want this sort of change applied to every book in your library.

Normally you would just select the Yes option to update the metadata (or the No option as you do not want to do such a significant change to your library).

Calibre2Opds ToolsBackup.jpg

CAUTION: This option changes every epub format file stored in the Calibre library. It is therefore a good idea to ensure you have a backup of the calibre library just in case anything goes wrong.

When you confirm that you have a backup then processing of epub files will start. A dialog of the form shown below is used so you can see what is happening.

Calibre2Opds ToolsRunning.jpg

NOTE. If you have a large library this command can take a long time to run as it has to open up every epub file in your library to check and update the metadata.

Help Menu

Calibre2Opds HelpMenu.jpg

TBD

Buttons

Top Buttons

Calibre2Opds Top.jpg

There are three buttons at the top left of the GUI that allow you to set the mode to be used.

calibre2opds can be set to run in a variety of modes to suit a users requirements. In each of these modes calibre2opds sets a list of options values, and disables a few options (required for the mode to have a specific value). Once a user has selected a mode it is unlikely they will want to change it very often.

The modes are:

  • Default mode: In this mode it assumed that the calibre library and the catalogs to be generated are all held in the same location (the Calibre library folder). A small change from earlier releases that will probably not be visisble to the end-user is that the catalog is generated in a temporary folder, and then moved to the Calibre library folder at the end of the generation phase.
  • Publication mode: The generated catalog is not moved to the Calibre library folder, but to another folder (called the target folder). In addition all Calibre Library files referenced by the generated catalogs (referenced books, and their covers) are also copied to the target folder.
  • Nook mode: The behavior is similar to the Publication mode except that destination folder is assumed to be the “My Documents” folder of a Nook’s internal SD-card. This mode generates a Trook-compatible catalog. Trook then can access all of the user’s books from the Calibre library that is now held locally to the Nook…The standard mode of operation with Trook is to generate a catalog in the Nook device mode, which copies the catalog locally on the Nook.
    However, if you want to access your Dropbox catalog ONLINE on the Nook, here’s how to do it :

    1. Use default mode on Calibre2Opds
    2. Use Trook in Compatibility level
    3. Generate catalog
    4. Go to Nook and use Trook
    5. Go to My Feeds
    6. Open the dropbox path to catalog.xml
    7. Bookmark it
    8. Refresh it
    9. You’re on!!!!

The same basic approach will allow you to access a Calibre2Opds catalog that is on the web even when it is not held in DropBox.

NOTE: If you set the Nook mode then the list of formats will be reset to those allowed by the Nook. As this is not visible on the main dialog tab thishas been known to take some people unaware.

The Donate button at the top right allows you to make a donation to the calibre2Opds team via PayPal. This is purely a voluntary option as the calibre2Opds development has been done for interest, not as a money making concern. However beer money is always welcomed if you really want to give something!

Bottom Buttons

There are a number of buttons along the bottom of the screen:

Calibre2Opds ButtonsBottom.jpg
  • Exit: This will exit calibre2opds without saving any changes to the configuration.
  • Reset to Defaults: This will set all parameter options to their default values.
  • Save: This will save the displayed configuration information and then exit Calibre2Opds. If you later run Calibre2Opds again these saved values will be the ones loaded and displayed. If you select this option you will be asked to confirm that you mean it by a dialog of the form
    Calibre2Opds SaveClose.jpg
  • Generate Catalogs: This saves the current configuration and then runs the generation process. You will be asked to confirm that you mean it by a dialog of the form
    Calibre2Opds SaveGen.jpg


Configuration Options

The configuration options are split across several tabs.  The different tabs are used to group related configuration items.  The tabs available are:

Main Options This tab has some fundemental settings that all users have to check is correct for their system.   This tab contains the one mandatory setting – the location of the Calibre library database.
Catalog Structure. This tab is used to control which sections of the catalog will be generated.
Book Details This tab controls how details of individual books will be displayed
Advanced This tab contains settings relevant to the generation of the catalog that are not appopriate to the earlier tabs as they are probably only relevant to experienced users.
Book External Links This tab allows users to over-ride the default URL’s that are used for generating links to external sites from within book details (assuming that option is not suppressed).  It is unlikely that most users will want to change these, but some users want to specify alternative language specific sites.
Custom Catalogs This tab allows the user to specify the details of custom catalog sections that are to be added to the Calibre2Opds generated catalog.

Main Options Tab

The options on this tab specify the things you are most likely to want to vary between runs of Calibre2Opds.

  • Language:
    This setting changes the language used by the Calibre2Opds in the user interface and generated catalogs.
    Use the standard ISO language code (e.g. EN, FR, DE…). Currently supported values : [DE, EN, FR, IT, ES, RU].
    Note that even if a language IS supported you may see still see some parts of the interface or the generated catalogs in English as calibre2opds reverts to using English any time it does not have a language specific translation for that field.
    Default: EN
    Translators are welcomed in terms of getting support for other languages included in Calibre2Opds or improving the support for those already present.
    If you would like to contribute, then read the  calibre2opds localization section of the documentation to see what is involved.
  • Database Folder:
    This is the directory in which Calibre stores its database (metadata.db) and ebook files. It is also the folder relative to which the calibre2opds catalogs will be generated when running in Default mode. Use the button to the right of this field to bring up a file selector dialog to help you set the correct folder.
    Defaultnone – setting this is mandatory.
  • Destination folder:
    This folder is set when not running in default mode (in default mode the catalog is simply created as a sub-folder of the Calibre library folder). When you specify a destination folder, this means you want a folder that contains copies of the books from the calibre library that are referenced by the generated catalog and also the generated catalog to be put into a sub-folder (as specified by the Catalog Folder setting) relative to the destination folder. This mode of running is typically used if you want to ‘publish’ the catalog to a remote web server.
    Default: none- setting this is mandatory in Publish mode
    CAUTION: Make sure that you do not set this location to an existing path that contains files that are not part of an existing catalog as these additional files will be lost when you publish the catalog to this folder.
  • Base URL:
    This is a setting that is not currently being used by Calibre2Opds but was in the drafts of the OPDS 1.1 standard (although it appears to have been removed from the final version). It was added here as a holder until we were ready to build on this part of the standard, but now that it is no longer in the final standard we are wondering if we should remove the setting.We are now re-thinking how we might use it.   One possibility is to have the catalog hosted on a completely different URL to the one that hosts the books and covers.
    Defaultblank.
  • Copy catalog to Database Folder:
    This option is disabled in the default mode as the in this case the catalog is generated as a sub-folder within the main Calibre library folder. This option is enabled when you are running in NAS mode to allow you to specify the location to which a copy of the calibre2opds catalog and the associated ebbok files should be made.
    Default:
  • Reprocess the epub metadata:
    This option will try to ensure that the metadata in any epub file matches the data stored in the calibre metadata database. To try and optimise this process it will only process epub files which are older than the date of the metadata.opf file stored with each book (indicating that the metadata has changed since the epub file was placed in the library. It is not an issue if this option is left set and no epub files have been changed as in this case no files will be changed. There is howerver still a runtime cost during the generation process to check with whether epub files or their associated metadata have been changed so there is a performance gain to not setting the option unecessarily.
    Default: Not set
    CAUTION: This option changes the actual epub files stored in the Calibre library. It is therefore a good idea to ensure you have a backup of the calibre library just in case anything goes wrong.
    Note that this is slightly different to the similar option on the Tools menu.   The one on the Tools menu processes every epub file in your library, while this one tries to optimise processing by only doing files where the metadata seems to be newer than the current ePub file.
  • Catalog Folder:
    Sets the name of the folder into which the catalogs will be generated. This setting is mandatory and cannot be set as empty. In default mnode, this folder will be one that is relative to the Database Folder, while in Publish mode it as a folder relative to the Destination folder.
    Default: _catalog
    CAUTION: Any existing contents of this folder will be lost when you generate a new catalog.
  • Catalog Title:
    Sets the title of the catalog, as seen in the OPDS feed and the HTML main page.
    Default: Calibre Library
  • Split Tags Using: Specifies a character that will be used to split the tags list in a tree. As an example you might use ‘:’ if your tags are named something like Action:ToRead:Asap and you want this to be split into ‘Action’, ToRead’ and ‘Asap’.
    Default:
  • Disable Splitting Tags: The Disable Splitting Tags provides an easy way to disable this function, but leave the split character specified in case you want to re-enable splitting at a later date..
  • Main Catalog Filter:
    This option allows you to supply a filter to the books that will be included in the generated catalog.   It uses the syntax discussed under Generation Time Search/Filter Criteria later in this section.A typical use might be where you may have a lot of tags in your library and you only want the catalog to be generated for those books which have specified tags.  You can then create a filter to either specify the tags to be included, or alternatively those to be excluded.  If this parameter is left blank then no filter is applied and  all books are included.
    Default: All books are included
  • Wikipedia language:
    This will change the Wikipedia links to make them point to a language-specific page ; use the standard ISO language code (e.g. EN, FR, DE…)
    Default: EN

Catalog Structure Tab

The options on this tab specify the strucrure of the catalog.   This controls what sections actually apear in the catalogs that are to be generated.

Catalog Structure
 
  • Do not generate OPDS catalogs:
    No OPDS catalogs will be generated. This will save space, but it will not speed up the generation process. Use it if you are only interested in the HTML catalogs.
    Default: OPDS catalogs are generated.
  • Do not generate HTML catalogs:
    No HTML catalogs will be generated. This will save space and and speed up the generation process. Use it if you are only interested in the OPDS catalogs.
    Default: HTML catalogs are generated.
  • Do not generate OPDS downloads:
    When generating the OPDS catalogs do not include the links that actually allow books to be downloaded. This can be useful if you simply want your list of books for reference purposes. Another case might be where you want to provide a demonstartion of the catalog facility without providing access to your real books
    Default: Download links are generated
  • Do not generate HTML Downloads:
    When generating the HTML catalogs do not include the links that actually allow books to be downloaded. This can be useful if you simply want your list of books for reference purposes. Another case might be where you want to provide a demonstartion of the catalog facility without providing access to your real books.
    Default: Download links are generated as long as OPDS ones are generated
    NOTES:

    1. It is not possible to have HTML Download links generated if they are not being generated at the OPDS level. This applies even if you have set the option to not generate OPDS catalogs.
  • Do not Include the “About calibre2opds” entry:
    Determines whether the top level entry giving information about calibre2opds is included.
    Default: The “About Calibre2Opds” section is included.
  • Do not generate the “Author” catalog: Suppress the option for generating the Authors section of the catalog.
    relevance.
    Default: Authorssection is generated.
  • Do not generate the “Tags” catalog:
    Suppress the option for generating the Tags section of the catalog. If you do not tend to have meaningful tags allocated to your books, then this section of the catalog is of no relevance.
    Default: Tags section is generated.
  • Do not generate the “Series” catalog:
    Suppress the option for generating the Series section of the catalog.
    Default: Series section is generated.
  • Do not generate the “Recent” catalog:
    Suppress the option for generating the Recent section of the catalog.
    Default: Recent section is generated.
  • Do not generate the “Ratings” catalog:
    Suppress the option for generating the Ratings section of the catalog. If you do not tend to have ratings allocated to your books, then this section of the catalog is of no relevance.
    Default: Ratings section is generated.
  • Do not generate the “All Books” catalog:
    Suppress the option for generating the All Books section of the catalog. If you have a large library these lists are unlikely to be useful on the basis that you are far more likely to know the Author Name or Series Name for a book you are interested in.
    Default:All Books section is generated
  •  Browsing by cover mode (HTML):
    Specifies whether the HTML catalogs should support browsing the books in cover mode. Many people find this friendlier than browsing by having thumbnails and associated links
    Default: No
  • Browsing by cover, do not split by letter:
    Specifies that in the HTML catalogs, sub-divisions by letter should not happen. This is particularly advantageous in small libraries where the split by letter can make it harder to easily browse the catalog.
    Default: No
  • Suppress Ratings in Books Titles:
    If not set, then the rating set in the Calibre database will be displayed in the details for each book. Many users do not set the ratings for the books in the calibre library so displaying the ratings would be meaningless. Setting this option means that the ratings are omitted from the Book details pages of the catalog.
    Default: Ratings are shown in book details.
  • Order the All Books section by series

These next few options allow you to control the way that authors and titles are both displayed and sorted.   It takes advantages that Calibre provides two fields for authors and titles: one for how authors are to be displayed in the user interface, and another for how they are to be displayed.   There are various tweaks in Calibre to control the relationship between the display format and sort format in each case.

These settings are used in Calibre2opds to provide a similar level of control for calibre2opds generated catalogs

  • Display Author lists using the Calibre ‘Author_Sort’ field
    The default behaviour in Calibre is to display authors in ‘first-name last-name’ format even though they may be sorted in ‘last-name first-name’ order.    In calibre2opds we have found that most people tend to want their lists displayed exactly the way that they are sorted.   In this case that means in the ‘last-name first-name’ format that is hte default for the Calibre ‘author_sort’ fields    If you want author lists to always be displayed in the way that Calibre has it stored in the ‘author’ field (typically first-name last-name) then clear this option.
    Default: The author sort field is used
  • Display Book lists using the Calibre ‘Title_Sort’ field
    The default behaviour in Calibre is to Display books using the title field.   This means that words such as ‘the’ and ‘a’ that are ignored for sorting purposes if they occur at the start of a book title are displayed with those words present at the start in lists of books.    If you want the list of books displayed to not have these present then set this option to use the ‘title_sort’ field which will move them to the end so that the displayed list follows strict alphabetical rules.
    Default:
    The ‘title’ field is used
  • SortAuthor lists using the Calibre ‘Author_Sort’ field
    This option allows you to specify how calibre2opds should sort a list of authors.   It would normally be expected that this would be the same way that you have sorted your authors in Calibre. 
    Default:
    The author_sort field is used.
  • Sort Book lists using the Calibre ‘Title_Sort’ field
    This option allows you to control how a list of books should be sorted.   It would normally be expected that this would be the same way that you have sorted your books in Calibre.
    Default:
    The title_sort field is used

Book Details Tab

The options on this tab are ones that affect how the details of individual books are displayed.

Book Details

The following describes these options in more detail.

  • Display Author names using the Calibre ‘Author_Sort’ field
    The default behaviour in Calibre is to display authors in ‘first-name last-name’ format even though they may be sorted in ‘last-name first-name’ order.    In calibre2opds we have found that most people tend to want authors in the book details to use the same rules as  Calibre.   If you instead want author lists to always be displayed in the way that Calibre has it stored in the ‘author_sort’ field (typically last-name first-name) then set this option.
    The difference between this option at what at first glance  appears to be a similar option in the Catalog Structure tab is that this is the option used when displaying the details for a particular book, while the other is the one used when displaying a list of book titles.
    Default: The Calibre ‘author’ field is used
  • Display Book Titles using the Calibre ‘Title_Sort’ field
    The default behaviour in Calibre is to Display books using the title field.   This means that words such as ‘the’ and ‘a’ that are ignored for sorting purposes if they occur at the start of a book title are displayed with those words present at the start in lists of books.    If you want the list of books displayed to not have these present then set this option to use the ‘title_sort’ field which will move them to the end so that the displayed list follows strict alphabetical rules.
    The difference between this option at what at first glance  appears to be a similar option in the Catalog Structure tab is that this is the option used when displaying the details for a particular book, while the other is the one used when displaying a list of book titles.
    Default: The ‘title’ field is used

The next set of setting allows you to control the amount of information that is shown on the book details page for any particular book within Calibre.   The Author, Title, Series and Comment are always displayed, but there are other fields in Calibre that you may want to also be displayed.   If you select any of these then the information is added before the main comment.

  • Include Series in the Book Details
    Calibre has a series field for books.  Most people will have set this to meaningful values and are interested in seeing this information in the Book Details page.    if you are not interested in seeing this, then unset this option.

Default: 

    Series

  is

    displayed
  • Include Tags in the Book Details
    The tags field in Calibre is used for a wide variety of purposes by Calibre users and thus the quality and usefulness of the information stored in this field is highly variable.  In most cases this information is likely to be of use so it is worth including it in the calibre2opds generated catalog.   If you do not want it displayed then unset this option.
  • Default:  tags is displayed
  • Include Publisher in the Book Details
    There is a field in Calibre that allow the Publisher for individual books to be stored.   However the quality fo the information that ends up in this field seems to be highly variable so unless you have been diligent in getting good data into Calibre it probably does not make sense to display this information in the Calibre2opds generated catalog.
    Default:  The Publisher field is not displayed
  • Include Published Date in the Book Details
    Calibre allows the published date for a book to (optionally) be stored.   It seems to be very variable as to the acucracy of that information so many people do not want calibre2opds to display the Calibre stoerd date.   If you set this option then the date field in Calibre will be displayed in the calibre2opds catalog as long as it is actuall set to something meaningul in Calibre.
    Default:
    Published date is not shown
  • Include Published Date as year in Book Details
    This opion is only relevant if the Published Date is going to be shown.
    Calibre always stores a date to include the day and month for dates.  Most people are not interested in this level of detail and are only interested in the year that the book was publuished.
    Default:
    Published date is shown as year only
  • Include Modified Date in the Book Details
    Calibre keeps track of the last time a particular book entry was modified in the Calibre metadata database.   If you would like this information to be displayed for books in the Calibre2opds catalog then set this option
    Default:  Modied date is not displayed
  • Do not generate cross-reference links:
    When an entry is generated for a book, then links can be generated showing linked information in the Calibre library such as other books in this series or other.
  • Do not generated external links: When generating an entry for a book then links can be generated to other sites such as Wikipedia or GoodReads for further information about the book or author.
    Default:External links are generated

Advanced Customization Options Tab

The options on this tab are ones that are rarely changed and are associated with fine-tuning the calibre2Opds output.

Advanced

  1. Included formats:
    The list of file formats that should be included in the catalog (separated by commas. The formats currently supported are: AZW, CBR, CBZ, CHM, DOC, EPUB, FB2, LIT, LRF, LRX, TXT, MOBI, ODF, PRC, PDB, RAR, RTF, ZIP. If you want all supported formats to be included then use ALL
    Default: ALL
    NOTES:

    1. A change to calibre2opds is being considered that would allow all formats that Calibre supports to be allowed, and not just those given in the list above.
  2. Include books without file:
    Include books without any associated ebook file in calibre. Supercedes the “–includeformat” option. It can be of particular use if you also have paper based books or a wishlist stored in your Calibre database.
    Default: No
  3. Include only one ebook file:
    Include only a single format of ebook. The list of formats given above is treated as a priority order and the matching format with the highest priority is sent. The purpose of this entry is to avoid sending multiple formats of the same book.
    Default: No
  4. Number of elements before split:
    When a catalog section has more items than this number, it will be split by the initial letter(s) of the items.   This algorithm is applied recursively, so that if at the next level there are still more entries than this trigger level the catalog will be split again on the next letter.As an example this might mean that you get a catalog section containing entries of the form:
    Authors starting with A
    Authors starting with B
    etc.
    and if these sections still contain more entries than the value of this trigger level they can be split further so that the Authors starting with A” entry could then lead to further entries so that you get entries of the form:
    Authors Starting with Aa
    Authors starting with Ab
    etc.This splitting by initial letter takes effect before pagination, so that if there are still too many items in a split catalog, it will be paginated as well.
    If you always want catalogs to be split by letter then you can set the split trigger condition to a very small value (e.g. 1), but in that case you should make certain that the value for limiting the number of levels splitting by letter will occur to a sensible value as well to stop excessibe levels of split being generated. The decision as to whether to split by level of split by pagination (aas described in the next titem) is very much a personal preference.
    Default: 75
  5. Maximum number of Levels of Split:
    As mentioned above, the algorithm for splitting a catalog section by initial letter(s) is applied recursively, and this can result in more levels of split than the user might want to happen.   This option allows you to control this behaviour by limiting the number of levels of splitting that will be done.   Once this limit has been reached, then only the pagination option appliss for splitting the entries within this level.
    Default:  1
    NOTES:

    1. Setting this value to 1 will reproducethe behavior of the calibre2opds 2.x versions which only supported splitting once on the first letter of a set of entries.
    2. If you set this value to zero you disable all splitting by letter, and only pagination will take effect.
  6. Number of elements before pagination:
    Pagination is used to control how many items appear on a single page at a given level of the catalog.  If viewing in many ePub readers this would result in a “Load More Results..” type entry being displayed. If being used in an HTML catalog then a Next Page link would be displayed.If you would like larger (or smaller) pages then set this to the desired value.   When a catalog level has more items than this number then pagination occurs.  If both Pagination and ‘Split by Letter’ are being used for aparticular catalog section, then the ‘Split By Letter’ by letter conditions are applied before deciding if Pagination is necessary.
    Default: 25
  7. Number of books in the “Recent” catalog:
    The number of books in the “recent additions” catalog. This will then be broken down into sections of increasing longer duration such as “Today”, This Week” with the number of sections being sufficient to contain the number you specify here. Note that the sections are cumulative, so “This Week” does not include any books that are already listed under “Today”
    Default: 99,999
    Is there any desire to have this based on age rather than the number of books?
  8. Maximum length of the summary text:
    Determines if the details are to be shown or a summary giving number of entries and number of pages. if you always want the number of entries and number of pages to be used, then set this to a small value such as 1
    Default: 250
  9. Do not show the series in the author catalog:
    When showing the books for an author, the default setting is to list all any series the author contributes to, followed by any books that are not part of a series. this option allows you to suppress the genreration of the series entries
    Default: Series is shown.
  10. In the Authors list page, skip the list of authors with the same initial:
    Default:  Not skipped
  11. Cover height:
    This option sets the size used to display cover images in the catalog whe  you show Book details.
    If you have not set the option to supprress the generation of Resized Cover images, then this option sets the height of the generated covers used to display Book details. Larger values for the cover height mean that larger cover image files are generated and the download time is longer, but the detail is better.
    If you have set the option to suppress the generation of Resized Cover images, then this option will still control the space used to display an image, but will have no effect on the amount of data downloaded for images at run time.
    Default: 550
  12. Thumbnail height:
    This options set the size used to display thumbnails within the generated catalog.
    If you have not set the option to supprress the generation of thumbnail images, then this option sets the height of the generated thumbnails (no need to exceed 125 pixels). larger thumbnails mean that larger files are generated and the download time is longer, but the detail is better. If you have set the option to suppress the generation of thumbnail images, then this option will still control the space used to display a thumbnail image, but will have no effect on the amount of data downloaded for images at run time.
    Default: 90
  13. Do not generate resized covers: 
    Use the existing Calibre cover.jpg file for the book details instead of generating a new image optimized to be used as a thumbnail. This will mean that there are less files generated for the catalog and a reduction in space used, but that at runtime cover images in the catalog will tend to display slightly slower as the cover.jpg files in Calibre are larger than the ones that calibre2opds generates as optimized to be used for thumbnails. The resized cover images are stored in your Calibre library alongside the book to which they relate.
    Default:  Resized covers are generated.
    NOTES:

    1. If you already have calibre2opds generated thumbnail files present in your Calibre library then they will be deleted. If you then subsequently unset this option option they will have to be regenerated.
  14. Do not generate thumbnails:
    Use the existing Calibre cover.jpg file for a book thumbnail instead of generating a new image optimized to be used as a thumbnail. This will mean that there are less files generated for the catalog and a reduction in space used, but that at runtime thumbnails will tend to display slightly slower as the cover.jpg files in Calibre are larger than the ones that calibre2opds generates as optimized to be used for thumbnails.  The thumbnail images are stored in your Calibre library alongside the book to which they relate.
    Default: Thumbnail images are generated.
    NOTES:

    1. If you already have calibre2opds generated thumbnail files present in your Calibre library then if you set this option they will be deleted. If you then subsequently unset this option option they will have to be regenerated.
  • Minimize number of changed files:
    Attempt to minimize the number of files that are changed in the generated catalog. If this is not set then all files in the catalog are regenerated. If it is set, then although all the files for the catalog are gernerated in a local temporary folder, some additional work is done during the catalog copy phase to avoid writing out as new any files whose content is identical to the previous run. This option is therefore of particular interest to those who store their catalog on a slow network drive, or on ‘cloud’ storage such as DropBox. For such systems the additional overhead of the checks required during catalog copy phase are more than gained back by the saving in the time that would otherwise be required to write out the unchanged files.
    Default: No
    NOTES:

    1. If the catalog is going to be on a drive that is going to be local to the system generating the catalog then this option is probably not worth using. The costs of calculating which files do not need copying because they are unchanged will normally be higher than simply doing the copy without making any checks.
  • Use external files for icons:
    The top levels of the catalogs have little graphics inidcating the section type in the catalog. Normally these are generated as embedded binary data in each page as this means that pages of the catalog load faster. However some reader devices  have browsers that cannot correctly handle such embedded images. Setting this option causes the images to be specified instead as links to external files.You may also set this option simply because it slightly reduces the file that is generated for each page.  The effect is not that large but can mount up on a large library.  If you do this you should be aware that there is a small runtime performance penalty as each icon image then has to be retrieved from the web server.
    Default: Icons are embedded as binary data.
  • Do not save bandwidth:
    Calibre2Opds will normally assume that if a thumbnail is already present it does not need to be regenerated. This means that the browser can cache such entries because the date of the file remains the same, thus optimizing downlod bandwidth. It also speeds up the catalog generation process.
    Default: thumbnails are not regenerated if they already exist
  • Encrypt the filenames: If set, the filenames will be encrypted in such a way that it is impossible to guess them, yet from one run to the next they stay constant. If not set then the names used are based on the catalog type and the Calibre internal database reference. Default: filenames are not encrypted
  • List of tags that Will Get an Additional Level:
    This facility is designed primarily for those who have large libraries although others may find it useful. It allows for further cross-indexing to be specified by allowing for tags that have a large number of entries to be sub-divided into another level similar to that provided at the top level of the catalog. An example of the way this might be used is to select Science Fiction and then find what recent books you have in this category. You can use wild cards when specifying the list of tags. As an example * would mean all tags, while Science* would mean all tags starting with Science.
    Default: No additional levels generated.
    CAUTION:
    Using this facility can lead to a large increase in the size of the catalog. The more tag values that are allowed to generate sub-levels the bigger the overhead
  • Minimum Books to Create an additional Level:
    This option is only used if you have set the previous value to tag values to generate sub-levels. It sets the number of entries that would need to be present at the current level befoer another sub-level is generated.
    Default: 50
  • Generate Search Index
    This option is used to determine whether you want support for runtime searching of HTML catalogs.
    Note: This facility is still regarded as ‘experimental’ and subject to change.   Feedback on its usefulness would be appreciated.
    Default:
  • Index book Comments 
    This option is only relevant when generating a Search Index.  It is used to determine whether the Comments field should also be considered when generating the list of keywrods that will be included in the search database. If not set, then only the title and author fields will be used.
    Default: -1
  • Maximum Number of Keywords
    This option is only relevant when generating a Search Index.  It determines the maximum number of keywords that should be included in the database. Limiting the number keeps the size of the database that needs to be sent to the client down, but increases the chance that the user will use keywords that have not been indexed. A value of -1 can be used to specify that no keywords limit should be applied.
    Default:
  • Index Filter Algorithm
    This option is only relevant when generating a Search Index.  This field is used to determine how a keyword list should be pruned down if it exceeds the maximum number that the user has specified. A number of algorithms are available as shown in the table below
    Default: renoveRare
Algoritm   Description of algorithm
RemoveRare   The least frequently used keywords are removed until the number left is within the maximum the user has specified.
RemoveCommon   The most frequently used keywords are removed from the index
RemoveMedian   Words are removed from the middle of the index leaving the most common and the rarest ones.

These setting allow to to customise the external links that are shown in the book details page for a given book. If you do not want external links at all then they can be suppressed by setting the option on the Catalog Generation tab).

 

Some links have ‘placeholders’ for variable parts of the URL that is used for the external link. These will appear as numeric values enclosed in braces (e.g. {0}). The tooltip for each field will describe the meaning of the variable values for the link to be used for that particular URL.

Some of the URL’s only get used if certain conditions are met:

  • Goodreads: The ISBN variant of the Book URL is used in preference to the title based one if the book entry in Calibre contains an ISBN value. The review URL is onlygenerated if an ISBN is present.
  • Amazon: The ISBN variant of the book URL is used in preference to the title based one if the book entry in Calibre contains an ISBN value.

Any specific URL can be suppressed by clearing the entry for that URL.

Reset buttons are available to reset any URL back to its original default value.


Custom Catalogs tab

This tab is used to all.ow new sections to the top level of the calibre21opds catalog that is about to be generated. 

  • Featured Books Search
    This exploits the new OPDS v1.1 feature of allowing a special featured books list to be specified. This can be done using either an existing Calibre Saved search or explicit search criteria entered here. If you do not want this feature then set this field to blank.If you use this feature then the way that the featured books is displayed in an OPDS client depends on the client in use as the OPDS standard says the client is free to handle the featured books list in any way it deems appropriate.In the calibre2opds HTML catalogs this is displayed as a simple list of books.
    Default
    blank
  • Featured Books Catalog Title
    The name to be given to this sub-catalog. This means that it could be used for something slightly different such as New Books if that is more appropriate to what you want to use it for.
    Default: Featured books

The next section of the tab allows for user specified sections to be added to the catalog using the “add a custom catalog” button.  The catalogs that are defined here can be of two types:

  • An internal catalog from your Calibre library according to search criteria.  For this type of custom catalog you will get a complete new catalog level generated inclusing authors, series, tags etc.  This is different to the presentation offered for the Featured Books catalog section mentioned above.
  • An external catalog have been generated independently from this run of calibre2opds.  Normally this will be a catalog provided by an external book provider.  However there is nothing to stop you using this to point to a catalog you generated in a different run of calibre2opds (this would most likely be of use to those running multiple Calibre libraries).

For each custom catalog you specify the following information:

  • Custom Catalog Title
    The name that you want to give to this catalog section.
    Default:  None
  • Custom Catalog Search or URL
    If the sub-catalog is to be generated from a selection of books in your Calibre library then this will be defined using Filter Criteria following the rules defined below.Alternatively you can use a URL to point to an externally generated catalog.   This could beone generated by a different run of calibre2opds, but a more likely use is an online catalog provided by a book provider.   The external URL is identified by the start of the text and the following action is taken:
Start of text Description
http:// https:// The URL is used as entered. The type of the link in both the HTML and the OPDS catalogs is set to indicate that the link points to an HTML based catalog.
opds:// Tis option is used unchanged as the URL, and the type of the link is set in the OPDS catalogs to indicate another level of OPDS compatible catalog. In reality the opds:// URL type is rarely used at te moment so this form is probably of not use to most people at the moment.
opds://http If this is encountered the the leading opds:// is stripped off and the remainder is assumed to be the URL to be used. For the OPDS catalogs the type of the link will be set to indicate another level of OPDS catalog. For HTML catalogs this has no special additional effect.   This allows you to point a section to an external catalog whose URL starts with http:// as is normally the case for such catalogs.

.


Search Criteria

Generation time Search/Filter Criteria

It is possible to specify search criteria that can affect catalog generation at several places:

  • Overall catalog
  • Featured books

The search criteria you can use build on the Calibre search facilities that user will already be familiar with. The search that can be specified is either an existing Calibre saved search or a search expression entered directly into calibre2opds using similar syntax to that used in Calibre.

Whether you use a Saved Search or one directly entered into calibre2opds, then the following restrictions apply:

  • Only the following fields can be used:
    Name Comments
    authors If multiple authors are present for a book then each one is tested in turn
    languages  
    publisher  
    rating  
    series  
    tags  If multiple tags are present for a book then each one is tested in turn
  • The field name should always be followed by a colon and then the expression to be evaluated enclosed in quote (e.g.tags:”=Science Fiction” )
  • The operator = can be used on all the field types supported
  • The operators < and > can be used on the rating field (e.g. rating:”>n”)
  • The keywords true and false can be used to check for the presence/absence of a value for a field (e.g. series:true).
  • The boolean operators and and or can be used between expressions to provide logical operations
  • The negation operator not can be used to negate the follwoing expression
  • Brackets can be used to group expressions.

It is intended that if the Search feature proves popular then the list of supported fields and the syntax allowed will be expanded to cover more of what Calibre allows. It is unlikely, however, to ever be as rich as the full Calibre search capability.

If you want to use a save search then one enters it into calibre2opds in the format

Saved:search_name

where search_name corresponds to an existing Saved Search in Calibre.

Alternatively you can enter the text of the search expression directly into calibre2opds search criteria field.

As search strings could easily be mistyped, it is strongly recommended that you first enter them into the Calibre search bar and test that they work as you expect. Once you are happy with them in Calibre then you can use Copy/Paste to tansfer them to calibre2opds without the risk of then mistyping them.

An example of a suitable search might be something like:

not tags:"=interest:1" and not tags:"=interest:2" and tags:"=State:toREAD" and not tags:"=Length:short" and language:="French"

An equivalent search using brackets to group some of the terms would be:

not (tags:"=Interest:1" or tags:="Interest:2") and tags:"=State:toREAD" and not tags:"=Length:short" and language:="French

Runtime Search Criteria

This facility allows the user to specify search criteria dynamically at runtime when using the HTML version of the catalogs.

To support this feature a search database needs to be generated that specifies the keywords that can be used at runtime. As this database needs to be downloaded to the client at runtime, one needs to be able to control its size.


Catalog Generation

When you select an option to start generating the catalogs then a dialog will be displayed as follows:

Calibre2Opds Confirm.jpg

Confirm this to proceed.

Calibre2opds will check the location that you have specified for the generation of the catalog. If there is not already an existing Calibre2opds catalog at that location then the following mesage will be displayed:

Calibre2Opds ConfirmPurge.jpg

CAUTION: Do not say yes to this prompt unless you are happy for ALL files at that location to be removed before generating the new Calibre2opds catalog. If Calibre2opds finds a catalog from an earlier run then this message is not displayed.

Confirm this to proceed.

While the generate is running a dialog is displayed of the form:

Progress Dialog

The step that is currently executing will be highlighted in bold.   The dailog will be udpated as Calibre2opds proceeds during the various stages of generating the catalogs with the time that each step completes being given.   The activity bar at the bottom of the dialog will display more detail about progress within a step.

If you have a large library, then the second stage that can take a relatively long time as at this point calibre2opds is making a check for every file that should be in the Calibre library. However you will see from the activity bar at the bottom of the dialog that calibre2opds is still working.

NOTE:  The same set of steps is always displayed even if some of them do not apply due to the configuration options you have selected.  The steps that are not relevant will effectively execute in an elapsed time of zero.

When Calibre2Opds has completed its run the following dialog is displayed:

Calibre2Opds Created.jpg

The catalogs are now fully generated.

You should look at the section on how to publish the calibre2opds catalogs to see if any additional steps are required before the catalogs are ready to be accessed online.

If for any reason you wish to abort a Calibre2Opds generation run early then use the “Stop Generating the Catalog” button.   The most likely reason for wanting to do this is because one realised that the configuration options set are not quite what you want.   As a generation run can take a long time on large libraries, when you select this option then the following dialog will be displayed.

If you accidentally pressed the button then simply select “Cancel” and the generation proceeds unaffected.   If you proess “OK” then the text in the Activity bar will be udpated to indicate that the user has activated the abortion of the generation process.  Note that the aborting can take a little while as Calibre2Opds can have a lot of temporary files that have already been generated and need to be removed.

When Calibre2Opds has finished aborting the current generation run, then a dialog will be displayed of the form:

Pressing “OK” at this point returns you to the main Calibre2Opds screen.


Advanced Use of Calibre2Opds

This section covers some options that are only going to be required in specific situations.

Command Line

The most likely reason you might want to start Calibre2Opds from the command line is that you want it to be run as a scheduled task. If you start Calibre2Opds can from the command line providing no runtime parameters then Calibre2Opds will start a generate using the last set of settings set via the GUI mode.

NOTE: This mean that you must have previously run the GUI to set up the paramters that you want to use for the batch run.

For those of you who do not know what we mean by saying the “Command Line” then we mean the ability to type in a program name followed by parameters rather than using a GUI based interface. This equates to:

  • Command Prompt under Windows.
  • Shell under Linux
  • Terminal on Mac OS

Calibre2Opds is run using a command of the form

java -cp OpdsOutput-2.4-SNAPSHOT.jar Main <profile>

where:

  • The name of the .jar file will be release dependent
  • The optional <profile> parameter can be used to specify the name of a profile which will direct Calibre2Opds to use this profile. If omitted, then the last profile used in the GUI is the one that will be used. The parameters for the run will be those that were earlier set using the GUI for the profile that is being used.

The command assumes that the java binary is on the system search path. If you are told that the java command is not found then it probably means that you have not installed the Java runtime system from http://www.java.com, the Java home site.

To help with running from the command line some batch style files are provided. Therefore you can also use

run.cmd <profile>  (Windows)

or

run.sh <profile>   (Linux/Mac)

while located in the Calibre2Opds install folder.

If you are under Windows and run this you will see a Command Prompt window open and Calibre2Opds will be running generating a catalog. It might look something like:

Calibre2Opds Command.jpg

This command line mode of running is particularily useful for running regular Calibre2Opds generate runs under automated control. This would typically be done using:

  • Windows: Task Scheduler (under Accessories)
  • Linux cron facility
  • Mac ?

Note


Mobile Calibre2opds

There have been requests for Calibre2opds to be run as a “mobile” application. This means the ability to run it from something like a USB stick without the need to install it on the machine that the USB stick is plugged into. Calibre can already be run in this mode so it would allow you to carry around your eBook library and associated software to manage it on a USB stick.

You can also do this using the Calibre2opds program. There is one pre-requisite in that the Java Runtime Environment (JRE) must be installed on the host machine. This is not an issue with Linux and Mac machines as Java comes pre-installed. On Windows machines this is not the case so Java needs to have been downloaded and installed before trying to run Calibre2opds in a portable mode.

You may also be able to take advantage of the fact that PortableApps.Com has Java working off a USB stick [1]

The one thing you need to do that is specific to the Calibre2opds Portable mode is to set up the CALIBRE2OPDS_CONFIG environment variable to point to to the location where the Configuration information is being stored on the USB Stick. If this environment variable is not set then the Calibre2opds software will look in the home directory of the user on the host machine – not what you want if your are trying to run in portable mode.

A sample batch file for running the Calibre2opds GUI on a Windows system would be something along the lines of:

CD Calibre2opdsConfig
SET CALIBRE2OPDS_CONFIG=%cd%
CD ..
CD Calibre2Opds
start javaw -cp OpdsOutput-2.4-SNAPSHOT.jar Gui

The above assumes that you have a folder structure on the USB drive that has sub-folders along the lines of:

  • Calibre2opds: folder holding calibre2opds files.
  • Calibre2OpdsConfig: folder holding calibre2opds configuration files

If you want to run the Command Line option of calibre2opds to generate catalogs using the saved parameters, then you can change the supplied run.cmd file to specify the calibre2opds configuration directory as shown above. This would result in a batch file with contents of the form

SET CALIBRE2OPDS_CONFIG=%cd%
java -cp OpdsOutput-2.3-SNAPSHOT.jar Main %*

Config Folder redirection

This an advanced feature that most users will not need. However it can be of particular use to those who use DropBox (or a similar Cloud syncing package) for storing their Calibre library, and have a slightly different path to this on the various machines that are being synced.

If you include a file with the name .redirect in the calibre2opds home (configuration) folder, then it is assumed that this is a simple text file that contains the path to a new location that should be used as the calibre2opds home folder.

As an example I might have two machines that are synced via dropbox and I have a .redirect file on the two machines which have contents of the form:

D:\My DropBox\Calibre2Opds\Config

on one machine, and

P:\My DropBox\Calibre2Opds\Config

on the other one.

The big difference between using this approach and using the CALIBRE2OPDS_CONFIG environment variable mentioned above is that it does not require calibre2opds to either be started from a script to set the environment variable, or having it is a machine wide setting.

Automatically updating calibre2opds catalogs

You can use the command line method of running calibre2opds in conjunction with your systems task scheduler. This will then run calibre2opds with the last set of stored parameters to generate a new catalog. The frequency with which you run this is up to you but it does mean that you will regularly get the catalog updated without having to remember to invoke calibre2opds to get up-to-date catalogs generated.

Windows

Windows allows you run tasks at scheduled times using the Windows Task Scheduler. This can be normally found at Start Menu->Accessories->System Tools.

You should set the task to run the RUN.CMD file that is supplied with calibre2Opds. It is up to you to decide the frequency at which the task should run and any trigger conditions that need to be met.

Linux

SECTION NEEDS MORE DETAIL

Mac

SECTION NEEDS MORE DETAIL

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 27 other followers

%d bloggers like this: