Calibre2OpdsRunning

Home Page	Calibre2opds User Guide						Developers Guide
	Overview	Installing	Generating	Publishing	Using	Troubleshooting

Generating Calibre2opds Catalogs

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. This works for all ebook types.
• 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. This works for ePubs only.
  • 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. This works for ePubs only.
  • If you're feeling adventurous, you can save your whole library to disk, which updates the metadata as it is saved, then delete your library and reimport all your books from the saved backup you just made. This is the best method of updating ALL metadata in ALL supported formats. If you do this, leave it running overnight; it will take some time.
  • Use the ebook-polish feature included in calibre version 0.9.19 and onward to reprocess ePub and azw3 ebooks ONLY. (This does not include Mobi.) Check the options for "Update metadata in the book files" and "Update the cover in the book files." Unlike converting the book to the same format, polishing only processes metadata and covers, not the whole book. The gory details may be found here.

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.</li>

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 commands of the following format:

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 X 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

These options are equivalent 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.

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:

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:

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

• Reprocess the metadata of all the ePub files
  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.
  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.<
  
  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 have 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).
  
  
  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.
  
  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.>/span>

• Reset the Encrypted Files cache
  If you are using the Encrypted files option to obscure the generated file names in the catalog then calibre2opds remembers the key used so that the name stay consistent between runs. If you use this option then a new key is generated so that new file names will be generated on the next run.

• Manage Logging (not yet ready for use
  This option is intended to allow for configuration of the Logging options via the GUI. It will not be of interest to the average user.

• Clear the Log Files(s)
  This option clears down the current log files. Normally Calibre2opds appends to any existing logs, so clearing them down means that you can be certain that any contents relate just to this run.

• View the current Log
  While Calibre2opds is running it keeps a log of significant stages in the generation process. There is also useful information stored in the log such as statistics on the calibre2opds generated library. This option simply opens the current log file.

• View older logs
  This allows you to look at logs from previous runs. It opens a dialog to the location to where the log files are stored so that you can select the one you are interested in viewing.

• View the sync Log
  This special log that is kept to show how efficiently Calibre2opds has been able to optimise the catalog generation process to reduce the number of changed files. It is primarily of interest to this who store their catalog on a remote server.

• Open the Configuration Folder
  Calibre2opds stores a small amount of information between runs such as the configuration settings that you last used. This option opens the folder where this information is held.

Help Menu

• Donate to the Project
  The Calibre2opds project has minimal costs as it makes extensive use of sites that provide free facilities for Open Source projects and the developers work in the spare time at no cost. There are a few minimal costs such as paying for domain names but these are not that significant. However feel free to donate to express your appreciation - if nothing else it can buy the developers an occasional beer!

• Open the Home Site
  This is the home site for Calibre2opds. It provides a central point to bring together all aspects of the Calivre2opds project.

• Support Forum
  This is a link to the support forum for Calibre2opds. It is where users should ask any generic questions on how to use Calibre2opds, or for further information of aspects of the software that are not clear.

• Issue Register
  This is alink to the system that is used to manage bug reports and enhancement requests concerning the Calibre2opds software.

• Online User Guide
  This is the main documentation for Calibre2opds. It is intended to enable the average user to use the calibre2opds software. It covers all aspects of day-to-day use of the Calibre2opds software.

• Online Developers Guide
  This is additional documentation that is targeted at those who want to know more about the development side of Calibre2opds. This might just be because you want to know how to build Calibre2opds from source, or because you want to be actively involved in Calibre2opds development. Calibre2opds is an Open Source project which means that anyone is welcome to get involved.

• Online Guide to Localizing Calibre2opds
  This provides information on ways you can help localize Calibre2opds. Strictly speaking it is a subset of the Developers Guide, but it has been broken out to emphasize the point that localization can be done by the average users with no special skills other than knowledge of the target language.

• Online Guide to Customizing Calibre2opds
  This provides information on ways you can customize Calibre2opds. Strictly speaking it is a subset of the Developers Guide, but it has been broken out to emphasize the point that customization can be done by the average users who may not think of themselves as developers.

• About
  This merely displays information about this particular version of Calibre2opds.

Buttons

Top Buttons

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:

• 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
  

• 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
  

• Help
  This calls up the online documentation covering the configurations options for the currently visible tab.

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 fundamental 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.<p>Use the standard ISO language code (e.g. EN, FR, DE...). Currently supported values : [DE, EN, FR, IT, ES, RU].</p><p>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.</p><p>This setting can also affect the order in which items such as a list of authors is displayed as the setting is used to determine sort order for non-ASCII characters (e.g. accented ones).</p><p>Default: EN</p><p>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 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.</p><p>Default: none - 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.</p><p>Default: none - setting this is mandatory in Publish mode and not possible in Default 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. We try to do some checks in Calibre2opds to protect against accidents but cannot guarantee that they are foolproof.
  

• Book URL
  <p>This setting allows you to specify the URL where the books making up the Calibre library reside. It is normally used in Publish mode where the catalog is being held on a different server the library (rather than the catalog being held as a sub-catalog of the folder holding the books). It is expected that one will typically have also set the option for the Target folder to only hold a catalog although this is not mandated.</p><p>Default: blank
  

• Copy catalog to Database Folder
  This option is disabled in the default mode as 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 ebook files should be made.</p><p>Default: not set
  

• Destination folder is catalog only
  This option is only valid in Publish mode. When set it specifies that the Destination folder holds the catalog rather than the catalog being a sub-folder of the Destination folder. It is typically used in conjunction with the option to specify a specific URL for where the books making up the Calibre Library are located.
  Default: not set
  

• 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 in Calibre (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
  NOTES
  • 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.
  • 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 optimize processing by only doing files where the metadata seems to be newer than the current ePub file.
  • Calibre itself now contains features that can make using this option in Calibre2opds unnecessary. These are the Calibre 'Polish Books' function, and the 'Modify ePub' plugin. The Calibre options offer more functionality than the one built into Calibre2opds, but the Calibre2opds function is retained because it was developed before the Calibre functionality so there is no development cost to retaining it, and anyway it can still be convenient.
    

• Auto-correct case mismatches
  It is possible for the case of filenames in the Calibre library to be different to what is stored in the Calibre metadata database for the library if the Calibre library is held on a case insensitive filing system (e.g. Windows) In theory this should not happen if the Calibre library is in a perfect state, but experience has shown that it does happen in practise. This can cause a problem at the Calibre2opds level if the catalog is hosted on a system (e.g. Linux) where case does matter in filenames. It can also cause a problem at the Calibre level if such a library is later moved to a system where filename case matters.<p>Calibre2opds can now detect such case mismatches and will take action according to this setting. If the auto-correct option is enabled then calibre2opds will attempt to correct the case to match the Calibre metadata database. If it is not set then Calibre2opds will log a warning message giving details of the mismatch found.
  Default: Not set
  NOTES
  • This option can change the names of folders/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.

• 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 (Calibre library 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
  This option is used to split a single tag into sub-parts, so is not relevant if you simply want a list of tags exactly as they are entered into Calibre. If you set this option it specifies the character that will be used to split the individual tags list into their sub-parts and treats the results as a tree. As an example you might use ':' if your have a tag named something like Action:ToRead:Asap and you want this to be split into 'Action', ToRead' and 'Asap'.
  Default: . (period)
  NOTES
  • You would typically use this setting if you are using the 'hierarchical tags' option within Calibre.
  • You cannot use the comma character, as this is hard-coded within Calibre to split a tag list into individual tags, not to sub-divide a single tag into constituent parts.
    

• 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.
  Default: set
  

• 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 default Wikipedia links to make them point to a language-specific page ; use the standard ISO language code (e.g. EN, FR, DE...)
  Default: EN
  

• Encrypt the filenames:
  Specify whether a form of filename encryption should be used on the catalog folders and files.
  If not set then the names used are based on the catalog type and the Calibre internal database reference.
  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. You will notice what appear to be random numbers are added at the start of all file/folder names in the catalog. These numbers are not truly random as they are based on a encryption key which specific to a user but they are not possible for a user trying to hack your library to guess.
  You are strongly advised to use this setting if you are going to make your library available via the internet and cannot put alternative robust authentication in place to protect access.
  Default: filenames are not encrypted
  

• Disable the Optimizer: Calibre2opds includes an optimizer that tries to minimize the time of a generation run by working out catalog pages that have not changed. To do this certain information is cached between runs and then used on the next run. This works extremely well if you have not changed the generation settings between the runs. However if you made changes to the settings then depending on what the change was that you made the optimizer may try and apply an incorrect optimization. The visible sign of this is that pages in the catalog are not updated to reflect the new settings. If you notice this then disable the Optimizer for the next generation run and this will be rectified. It is recommended that you then then enable the optimizer again as it provides significant improvements in the time of a generation run.
  Default: Optimizer is not disabled
  

---

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.

• 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.>br>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:
  • 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.
  Default: Authors section 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.

• Language as Tag
  This allows you to treat the Language settings for books as though they were a tag of the form Lang:?? where ?? is the two digit ISO code for the language. This allows for behavior consistent with older versions of Calibre where Language was not an explicit metadata field. It can also be used to get a section in the Tags sub-catalog for specific languages.
  Default:
  NOTES:
  • If the option to omit tags from the catalog is also specified this is applied after this setting has taken effect. This allows you to exclude any specific languages showing up if you want to concentrate to those that are not the default for your library.

• 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
  The following screen shots illustrate the difference between these two modes:

  Normal Browsing Mode		Browse by Cover mode

• 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

• Do not show the Series in the author catalogs
  Many people like to see what series an author has been involved in writing books for. If this option is not set then an author will have all the series he is involved in listed first followed by the books that are not part of a series. At the top of the list of series is an entry that gives the full alphabetical list of books by this author for the cases where you want to see such a list independent of the series the books are part of.. If you do not want series given this special treatment then set this option and you will then get a simple alphabetical list of books by this author.
  Default: This option is not set.

• 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 titles under book details.

• Order the All Books section by Series
  This allows you to specify whether you want the All Books catalog to simply be sorted by Title, or whether you prefer Series to get special treatment so that the books of a series are listed together. It is expected that most users will use the Series sub-catalog instead but enough users have requested this feature to cause it to be added. Note that the All Books sub-section within an author is always sorted purely by title regardless of the value of this setting.
  Default: No

The 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.

• Sort Author 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.

• Tags to omit from the Tags catalog
  This allows you to specify that there are tags that in your library that you do not want to include in the Tags sub-catalog. Many people include tags for special purpose that they would rather not have explicitly called out in the tags sub-catalog. You can use a simple wildcard of the form Science* to omit all tags starting with Science.
  Default: none set
  Notes
  • Specifying tags to be omitted here does NOT stop them being shown within Book Details pages. It is assumed that you would like to see all tags associated with a book even if you do not want to have a section within the Tags sub-catalog for them.
    Feedback would be welcomed on whether this is actually desirable behavior)

---

Book Details Tab

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

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.<p>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.<p>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.

• Display Series using the 'sort' order
  This option is only available if you have elected to use the option to use the 'Library Sort' option for series name in the Catalog Structure tab. If this is set then any 'noise' words (such as 'a' or 'the') are moved to the end of the Series name that is displayed (e.g 'The SeriesName' is displayed as 'SeriesName, The'. Most people seem to prefer the noise words to be displayed in their natural position at the start of the Series name but some prefer the Series name to be displayed as it is when sorted using the 'Library Sort' method.
  'Default: The 'series' field is used unchanged.

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 Title in the Book Details
  This controls whether the Title is displayed in the Book details (and in Book list). At the moment this option is always enabled and the user cannot disable it. This option has been added to the GUI with some thought of future enhancements.
  Default: Title is displayed.
  If you have a specific Use Case for this feature then please provide the details as it may mean that being able to change this option is given a higher priority for development purposes.
  

• Include Author in the Book Details
  This controls whether the author(s) is displayed in the Book Details pages (and Book lists). For normal books you almost certainly want this option enabled. However if you have separate libraries for different types of eBook then you may decide that for some types of eBook displaying the Author(s) does not make sense. In such a case you can disable the inclusion of the author(s).
  Default: Authors are displayed.
  If you disable displaying the authors then you are not allowed to try and generate an Authors sub-catalog. If you have a Use Case where this assumption is incorrect then please provide appropriate feedback.
  

• 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
  </strong>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 published.
  Default: Published date is shown as year only.

• Include Added Date in the Book Details
  Shows the date in which a particular book entry was madded tothe Calibre metadata database. If you would like this information to be displayed for books in the Calibre2opds catalog then set this option
  Default: Added date is not displayed.

• 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: Modifed date is not displayed.

• Include the Download Size in the Book Details
  Set this option to display the size of the eBook file against the Download links on the Book Details pages for the HTML version of the catalog. The download size will always be displayed in a friendly human readable format (e.g. 121 KB, 2.0 MB). For most eBooks this is probably not that important as eBook files tend to be small, but for some file types (e.g. comic book files) that can be very large and thus take a while to download this is useful information to have displayed.
  Default: Book size is displayed.

• Custom Fields to Include in Book Details
  Calibre allows users to set up Custom fields within their Calibre libraries. This option can be used to specify that such fields should have their Description and value added to the Book Details in a similar way to the standard metadata fields such as Series, tags etc. The list of fields is provided as a comma separated list of the field names specified within Calibre. There is also a checkbox available that can be used to get an entry for the Custom Columns to be included in Book Details even when no value has been set at the Calibre level.
  Default: No custom fields are included
  
  NOTES:
  • If you specify any such fields to be added then they are added to the book details in the order listed.
  • Custom Column values are only shown under Book Details when Custom Column values have actually been entered into the Calibre database for the book in question unless you explicitly set the option to always have them included.
  • Calibre normally expects custom fields to have their names preceded by the # character, but when entering the names here the # is optional and assumed if omitted.
  • Calibre2opds ignores the case of the names entered. Therefore you cannot have two different fields whose only difference in their names is the case of some of the letters.
  • Text fields that start with http:// or https:// will have the relevant HTML added to turn them into links. The Custom Column title will be used as the description field for the link.

• 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.
  Default: Cross-reference links are generated

• Generate Cross-References for single book
  If there are no additional books that satisfy the cross-reference criteria, then suppress the generation of the cross-reference entries. Some people prefer not see a cross-reference entry in such a case, while others like to always see the cross-references regardless.
  Default: Cross-reference links are generated

• Include authors in cross-references
  This option is used to specify whether you want authors to be included in cross-references. This provides a quick way to get from the book entry to see other books that this author has written.
  Default: Authors are shown in cross-references

• Include tags in cross-references
  This option is used to specify whether you want tags to be included in cross-references. If you have been disciplined and limited the number of tags that you have then you probably DO want tags included in cross-references. However metadata sources can provide vast arrays of tags for some books, and if you have simply accepted all such tags you probably do not want them all made into cross-references
  Default: Tages are shown in cross-references.

• Include series in cross-references
  This option is used to specify whether you want a cross-link to a series that this book is part of. This provides a quick way to get from the book entry to see other books in the same series. If the book is not part of a series then this cross-reference will not be shown.
  Default: Series are shown in cross-references

• Include Ratings in cross-references
  This option is used to specify whether you want a cross-link to all books with the same rating. This provides a quick way to get from the book entry to see other books that have the same rating. Whether this is likely to be of any use depends on how diligent you are about keeping ratings meaningful, although it is suspected that most people would NOT be interested in this type of cross-reference. If the book has no rating then this cross-reference will not be shown. Feedback would be appreciated on whether this option is in fact used - if no-one uses it then it is a candidate for removal.
  Default: Ratings are not shown in cross-references

---

Advanced Tab

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

• Included formats:
  The list of file formats that should be included in the catalog (separated by commas. The formats currently supported are: AZW, AZW3, CBR, CBZ, CHM, DOC, DOCX, EPUB, FB2, HTMLZ, LIT, LRF, LRX, TXT, MOBI, PDF, PRB, PDC, RAR, RTF, ZIP. If you want all supported formats to be included then use ALL
  Default: ALL
  NOTES:
  • If you want to extend the list of file types that Calibre2opds should treat as ebook files then the mechanism for doing this is described in the Customization section of the Developers Guide at Extend list of supported formats.

• Include books without file:
  Include books without any associated ebook file in calibre. It can be of particular use if you also have paper based books or a wishlist stored in your Calibre database.Default: No

• 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

• 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.<p>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 (as described in the next item) is very much a personal preference.
  Default: 75

• 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:
  • 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.
  • If you set this value to zero you disable all splitting by letter, and only pagination will take effect.

• 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

• 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". The maximum value currently allowed is 500 as it ha been found that very large numbers can cause issues. It might be possible to increase this limit. If you have a need for this please raise this a request and give the rational
  Default: 500
  Is there any desire to have this based on age rather than the number of books?

• Maximum length of the summary text:
  this relates to the summary text shown as the second line when displaying entries for navigating around the catalog. The value set here Determines if the details are to be shown on the summary line or an alternative format giving number of entries/pages. The count format is used if the summary length would otherwise exceed the value you set here. 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: 30

• Maximum length of a Book Summary:
  This is the summary that is used when displaying a list of books. In HTML catalogs, many people like to reduce the size to make the book listing more compact. If you do not want to limit the length of the summary either set a very large value, or use the special value of -1.
  Default: 250
  NOTE: The full summary information is always shown if you actually look at the full details page for a book.

• 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.

• In the Authors list page, skip the list of authors with the same initial:
  Default: Not skipped

• Cover height:
  This option sets the size used to display cover images in the catalog when you show Book details.
  
  If you have not set the option to suppress 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, the space required for storing cover images is larger, and the download time is longer, but the detail is better. Conversely set the size smaller for lower resolution images that will occupy less space.
  
  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

• 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

• 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:
  • 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.

• 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:
  • 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.

• Use external files for icons:
  The top levels of the catalogs have little graphics indicating 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.

• Use external image files:
  Normally images (covers and thumbnails) are held as external files with one image per file. If this option is not set then the images are embedded as binary data in each page. This means that you end up with less files in the catalog, but the pages are larger.
  
  You are most likely to want to use this option when you are using the option to create a ZIP of the catalog and you want to reduce the number of files that in the catalog.
  
  Default: External image files are used.
  
  NOTES
  • Not all browsers can handle image files embedded as binary data into the HTML files. You can expect mainstream browsers to be happy with this, but some of those built into eReader devices (e.g. Kindle) may have trouble with such images.
  • Not all eReader devices/applications can handle image files embedded as binary data into the XML (OPDS) files. You will need to experiment to see if this affects your device/apps.

• Include cover images within the catalog:
  Normally the images used for displaying covers and/or thumbnails within a calibre2opds generated catalog are held in the same folder within a Calibre library where the books reside, and the pages of the catalog will reference these images from that location. If you set this option to hold cover images within that catalog than copies of the images are instead held within the catalog itself. A typical use of this feature is expected to be when you want to be able to create an off-line version of the catalog for browsing.
  Default: images are not included as standard
  NOTES
  • It is probably not a good idea to have the option to set the options to Not use Resized Images or to not generate thumbnails (i.e. to instead use existing Calibre cover images) if you set this option as that would tend to lead to unnecessarily large image files (and thus increase overall catalog size).
  • If you want to keep the number of files in the catalog down, then you may also want to make sure that the option to use External files for Images is not set. this will keep the number of files down at the expense of individual XML/HTML files being larger. This may be important when creating a ZIP file to be treated as a web archive as it is possible that the software to handle such an archive is limited in the number of files it can handle.

• Use thumbnails for cover images:
  This option is used to keep the amount of space that will be occupied by cover images down to a minimum at the cost of cover images in book details possibly appearing a bit blurred. It is also often appropriate if you are using the option to include cover images within the catalog if you want to keep the catalog size down and do not mind having lower resolution cover images to achieve this.
  Default: not set

• Create ZIP of catalog:
  This option will create a ZIP of all the files that are in the catalog. The main use of this facility is expected to be in conjunction with the option to include cover images within the catalog to provide a facility for off-line viewing of the catalog. This is quite likely to be something one might want to do with the catalog on a table or phone where there are commonly apps available that can treat a ZIP as a virtual web site (e.g. sites-2-go on iOS systems). If using this option you might want to also use the option to use thumbnail images for covers to keep total size down.
  Default: No ZIP is created.

• Omit XML files from ZIP of catalog:
  This option only relevant when you are generating both the XML (OPDS) and HTML variants of the catalog. It is intended to be used when you intend the resulting ZIP file to be treated as a catalog on a virtual web site so that the XML files are off no use and would just occupy space in the ZIP.
  Default:

• 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:
  • 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.

• Minimum Books to Create an additional Level:
  This option is only used if you have set the next option value to the tag values to generate sub-levels. It sets the number of entries that would need to be present at the current level before another sub-level is generated.
  Default: 50

• 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.
  NOTES:
  • Using this facility can lead to a large increase in the size of the catalog and the time taken to generate the catalog. The more tag values that are allowed to generate sub-levels the bigger the overheads so limit the list of tags to those you really want an additional level for.
  • It may be more appropriate for many cases to instead use the Custom Catalog feature to instead create an additional top level entry to create a level for a specific tag or tag combination. One advantage of the Custom Catalog approach is that one can combine a specific mix of tags to get the additional level rather than one tag only.

Settings of particular relevance for Cloud based catalogs (e.g. DropBox)

There are a number of settings on the Advanced tab that can improve things for user who store their catalogs on Cloud based services such as DropBox.

• On the Main tab, set the option to use encrypted file names. If you are using a service such as DropBox you cannot provide protection on the Public folder so you do not want to make it easy for your library to by found as you could then be accused of attempting to infringe copyright. Setting this option make sit impossible for a third part to guess the filenames used in the catalog. Note, however, that this is not foolproof security.
  
  

• Make sure the option to Minimize changed files is set. This will reduce the number of files that need to be synced back to the cloud after generating a new catalog.
  
  

• Set the options to not generate optimized cover or thumbnail images. This will reduce the number of files in the catalog and reduce the space occupied. The Cover image setting is much more important than the thumbnail setting as cover images are much larger than thumbnail images.
  
  

• Set the option to use External Icon files. This reduces the size of the xml/html files within the catalog. The gain is minimal so this setting is less important than many of the others.
  
  

• Set the option to use External Images. This significantly reduces the sizes of the xml/html files within the catalog.
  
  

• Set the option to use thumbnail images for covers (optional). This means that the smaller thumbnail images are also used for displaying covers on book details. This can, however, mean that the cover images are blurry due to the reduction in resolution so you have to decide if the trade-off suits you.
  
  

---

Book Links tab

These setting allow to control and customise the external links that are shown in the book details page for a given book.

• 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

• Open external references in a new browser window: When opening a book reference that is on an external site (the ones listed below) use a new browser window.
  Default: External window is used

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 allow new sections to be added to the top level of the calibre2opds catalog that is about to be generated.

• Featured Books Search
  This exploits the capability introduced in OPDS v1.1 fof allowing a special featured books list to be specified. You can do this using either an existing Calibre Saved search or explicit search criteria entered here. In both cases the search terms must conform to that specified for the calibre2opds search capability.
  
  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 (including whether it is displayed in the first place) 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 if this options is set then the top level catalog will contain a new entry using the name you selected for the Feature Books title, and if you select this entry then the results are this is displayed as a simple list of books.
  Default: blank (i.e. Featured Search not used)
  
  

• 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
  
  

• Open external references in a new browser window
  Open any custom catalog references that refer to an external site in a new browser window. If not set then the current window is reused
  Default: A new browser window is not used
  
  

The next section of the tab allows for a variable number of user specified sections to be added to the top level catalog using the "Add" button. The catalogs that are defined here can be of two types:

• An internal catalog generated from your Calibre library according to search criteria. For this type of custom catalog you will get a complete new catalog level generated including authors, series, tags etc. This is different to the presentation offered for the Featured Books catalog section mentioned above. The syntax of the Search field must conform to the rules detailed below. If the syntax is incorrect then you may get a runtime error about the syntax at the stage where you try and generate the catalog.
  
  

• An external catalog that has 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).
  
  It also need not necessarily even be a catalog - it could simply be a web page that you want to show a link to at the top level of the catalog you are about to generate
  
  

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 URL text	Description
	HtmlURL:string	The value of string is assumed to be a valid URL that points to an HTML catalog or perhaps just a web page. It can be a fully qualified URL, or a relative URL. You can optionally surround the value of string with quotes (") to improve readability - if they are present they will be removed when generating the URL's. The use of Relative URL's will normally only make sense when you are trying to link multiple Calibre2Opds generated catalogs together for users with multiple Calibre libraries. Special characters not allowed in URLs (e.g. space character) are represented by the sequence %xx where xx is the hex value in the ASCII character set.
	OpdsURL:string	The value of string is assumed to be a valid URL that points to an OPDs catalog. You can optionally surround the value of string with quotes (") to improve readability - if they are present they will be removed when generating the URL's. When used with an HTML catalog it is functionally equivalent to the HtmlURL prefix except that any .xml extension is changed to .html. Special characters not allowed in URLs (e.g. space character) are represented by the sequence %xx where xx is the hex value in the ASCII character set.
	http:// https://	DEPRECATED (from Rev 270 onwards) - use the HtmlURL: prefix instead 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:http:// opds:https://	DEPRECATED (from Rev 270 onwards) - use the OpdsURL: prefix instead 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 OPDS catalog whose URL starts with http:// or https:// as is normally the case for such catalogs.

Here are some examples of entries you might want to consider adding using publically available book sources:

	Title	Custom catalog search or URL	Comments
	Baen Free Library	HtmlURL:http://www.baen.com/library/intro.asp	Baen offer a selection of DRM free Science Fiction and Fantasy books from their catalog
	Project Gutenberg (HTML)	HtmlURL:http://www.gutenberg.org/	A huge source of books in the Public Domain on a HTML feed
	Project Gutenberg (OPDS)	OpdsURL:http://m.gutenberg.org/	The Project Gutenberg catalog on an OPDS feed
	Feedbooks	OpdsURL:http://www.feedbooks.com/catalog.atom	This is an example of an OPDS feed on a http:// URL
	Munseys	HtmlURL:http://munseys.com/	A source of books that are often hard to find

and some using your own library

	My Special Books	Saved:xxx	A Saved Calibre search called xxx. Note any such search must conform to the limited vocabulary defined in the Search Criteria section below or you will get a runtime error in Calibre2opds. The results would appear under a top level section called My Special Books
	Science Fiction	tags:"=Science Fiction"	All the books in your library with the tag called Science Fiction. This is an exact match so would exclude books with a tag such as Science Fiction/Fantasy. The books would appear under a top-level heading of Science Fiction.
	Romance books	tags:"Romance"	All the books in your library with the tags that contain the string Romance. This would include tags such as Historical Romance or Contemporary Romance as well as plain Romance. They would appear under a top level heading of Romance books
	Guidelines Second Library First Library	HtmlURL:"../Guidelines/guidelines.html" OpdsURL:"../../Second%20Library/_catalog/index.xml" OpdsURL:"../../First%20Library/_catalog/index.xml"	This illustrates several features. First is a link to the guidelines.html document that was created with instructions on using this particular library. Then an example of the way of linking two Calibre2opds generated catalogs. The first entry would be used in the catalog for library 'FirstLibrary' to provide a link to 'SecondLibrary', and the second entry would be used in the catalog for 'SecondLibrary' to provide a link back to 'FirstLibrary' This example also shows the use of quote (") characters around the URL to improve readability. Finally this example illustrates the use of the '%20' sequence to represent a space as spaces are not allowed in URLs.

The above are only a small selection. There are plenty of other sources that you might like to have linked to you Calibre2opds catalog.

Once you have added such Custom catalog entries, you will also be given a Delete button alongside each entry to remove it if you later decide it is no longer required.

The following screenshot shows what you can expect to see in a generated catalog when you have set up Custom catalogs

In this example there are 3 internal custom catalogs for "Audio Books", "Paper Books" and "Wish List" that have been set up using searches, and an external one "Guidelines on Using Library" that has been setup as a URL link to an external entry. This last one illustrates the point that when using URL links they need not be to an actual catalog, just any valid web page.

Search Options Tab

This tab is used to specify client-side search options.

You will initially get a dlsplay of the form:

• Generate Search Index:
  This option is used to determine whether you want support for runtime searching of HTML catalogs. This feature only applies to HTML catalogs and runtime searching of OPDS catalogs is not supported.
  Notes:
  • This facility is still regarded as 'experimental' and subject to change. Feedback on its usefulness would be appreciated, particularly in light of the next point
  • The current functionality that has been used is not supported by many modern browsers. As such this option must be considered as deprecated until an alternative implementation can be found. This will be treated as a low priority change unless positive feedback is given as o how useful it could be.

Default:

If you decide that despite the caution you want to activate the search setting the above checkbox changes the display to give you the options you can set:

• Index book Comments:
  This option used to determine whether the Comments field should also be considered when generating the list of keywords that will be included in the search database. If not set, then only the title and author fields will be used.
  Default: Comments are not indexed

• Maximum Number of Keywords
  This option 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: -1

• Index Filter Algorithm
  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: removeRare

	Algorithm	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.

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 although only a subset of the full Calibre search syntax is supported. 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	If multiple languages are present for a book then each one is tested in turn
	publisher	The values true or false can be used to test if there is any publisher set.
	rating	The values true or false can be used to test if there is any rating set.
	series	The values true or false can be used to test if there is any series set.
	tags	If multiple tags are present for a book then each one is tested in turn. The values true and false can be used to test if any tags are present.
	formats	If multiple formats are present for a book then each one is tested in turn. The values true or false can be used to test if there are any formats at all.

• All entries are case independent so you do not need to worry about this when entering a value.
• 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 expression can optionally start with an operator.
• If no operator is present then a contains operation is assumed (this is the same assumption that Calibre makes). As an example entering tags:"Romance" would give match any tag that contained the string Romance regardless of where it appeared.
• The operator = can be used on all the field types supported to specify an exact match.
• 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 following 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 saved Calibre search then one enters it into calibre2opds in the format

 Saved:search_name

where search_name corresponds to an existing Saved Search in Calibre. Note however the saved Calibre search must still conform to the restrictions documented here.

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

To show what this might look like when used to set up some custom catalog entries the following screen shot might help:

Runtime Search Criteria

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

DEPRECATED

The experimental Search feature in Calibre2opds was implemented using the Web SQL feature that was part of the draft HTML 5 specification. This feature has since been withdrawn from the standardization process, so most of the current browsers do not implement this support. The only ones that we are currently aware of are Google's Chrome and Apple's Safari browsers. If you try and invoke this feature on a browser that does not support WebSQL you will get an error message at runtime.

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:

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:

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:

The same set of steps is always displayed even if some of them do not apply due to the configuration options you have selected. Any steps that are not relevant to this run will be dimmed and these steps will be skipped over. The step that is currently executing will be highlighted in red.

The dialog is updated as Calibre2opds proceeds during the various stages of generating the catalogs. As each stage completes the time at which it completed is given which allows you to work out how long each stage has taken to complete.

The progress bar at the top of the dialog attempts to show progress within the current step. 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 Authors stage is likely to take a noticeably longer time as at this point calibre2opds is making a check for every book file that should be in the Calibre library as well as generating the Authors sub-section of the library. However you will see from the activity bar at the bottom of the dialog that calibre2opds is still working. Subsequent stages will run faster as calibre2opds can make use of information that has been cached from running the earlier stage of the generation.

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

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.

Calibre2opds Log file

When Calibre2opds is running a generation run then messages are written to a Log file giving information about the run. Calibre2opds has extensive levels of logging embedded in the binary and it is defined at several levels so that it can be set to what is appropriate for the average user or to more detailed levels that are only of interest to Calibre2opds developers. The default settings for the level of detail are set so that the messages are likely to be informative to the average user (although additional detail can be specified using the techniques defined in the Troubleshooting section). The option to view the current log file is available via the Tools menu in the calibre2opds GUI.

Several categories of information are logged that are likely to be of interest to a typical Calibre2opds user:

• ERROR: These are logged when is found that is likely to stop Calibre2opds from completing its run successfully. Depending on the type of error it may be something the user can correct, or something that needs to be reported to the calibre2opds developers to get a resolution.
• WARN: These are messages that are logged when some small inconsistency is found that will not stop calibre2opds from completing successfully. In most cases they will refer to items that can be corrected by the user using the Calibre program.
• INFO: These are messages that give generic information about this particular Calibre2opds generation run. They may be of interest to the user to look at but are not deemed important enough to be explicitly mentioned in the dialog displayed at the end of the generation run for a library.

At the end of a generation run the completion dialog will display counts for the number of messages logged of type ERROR or WARN. The user is entitled to ignore these but it the counts are intended to indicate when there might be messages of interest in the log file.

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 parameters that you want to use for the batch run. An alternative is to run the GUI on another system and then copy across the configuration file.

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:

• WIndows: Command Prompt
• Linux: Shell
• Mac OS: Terminal

Calibre2Opds is run using a command of the form

 java -cp OpdsOutput-3.4-SNAPSHOT.jar Gui <profile>

for GUI mode or

 java -cp OpdsOutput-3.4-SNAPSHOT.jar Cli <profile>

for batch mode 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. If you specify a profile that cannot be found, then in batch mode the run will be aborted with status code -3 after logging an appropriate error message. If running in GUI mode then the error is ignored and the current default profile loaded.

The command assumes that the java binary is on the system search path or can be found in one of the standard locations. 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:

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: ?

Specifying the Calibre2opds configuration folder

Normally Callibre2opds will look for its configuration information in the users home folder. For most users this is sufficient, but for those who want a bit more control then it is possible to have the configuration information in any of the following locations :

• An explicit location specified via the CALIBRE2OPDS_CONFIG environment folder.
• The users home folder (the normal default).
• If the home folder exists, then a check is made for folder redirection as described below.
• The location at which the calibre2opds binaries have been installed. This last option is not recommended as on many systems write access is not allowed.

The facility for explicitly specifying the Calibre2opds configuration folder is typically used when setting up a portable/mobile installation. It can also be of use if you want to use multiple versions of Caibre2opds on the same machine with different configuration folder locations for the different versions.

On a Windows system Calibre2opds is started in GUI mode using the RUNGUI.CMD file. This is a batch file that can be edited with any editor capable of handling text files. You can make this change permanent by inserting a line that :

 SET CALIBRE2OPDS_CONFIG=D:\Calibre2OpdsConfig

at the start of the file.

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.

 SET CALIBRE2OPDS_CONFIG=D:\Calibre2OpdsConfig
 java -cp OpdsOutput-3.1-SNAPSHOT.jar Main %*

The only difference when running in batch modes is that (on Windows systems) the java command is used instead of the javaw command and the Calibre2opds program is started with slightly different parameters.

Config Folder redirection

This an advanced feature that most users will not need. However it can be of particular use to those who use Calibre2Opds on multiple computers and also use a cloud syncing service such as DropBox; Copy.com; OneDrive (was SkyDrive); 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 (in the .calibre2opds subfolder of the users home folder )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

On Linux systems the normal way of running scheduled jobs at regular intervals is to use the cron sub-system. You would set it up to run calibre2opds via the run.sh' file that is provided as part of calibre2opds.

SECTION NEEDS MORE DETAIL

Mac

SECTION NEEDS MORE DETAIL

Specifying the Calibre2opds temporary folder

Calibre2opds creates a lot of files in a temporary folder while it is running. The default location for this folder is the standard system location of temporary files and folders. If you want Calibre2opds to use a different location then this can be done by setting the CALIBRE2OPDS_TEMP environment variable before starting Calibre2opds.

e.g. (on Windows)

 SET CALIBRE2OPDS_CONFIG=D:\C2O_TEMP
 RUNGUI.CMD

would set the folder for temp files and then start Calibre2opds in GUI mode. Alternatively you can insert the SET command into the RUNGUI.CMD file, or set CALIBRE2OPDS_TEMP as a standard environment variable via the Properties of 'My Computer'

In a similar way, 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 or run.sh file to specify the calibre2opds configuration directory as shown above. This would result in a batch file with contents of the form