-
Notifications
You must be signed in to change notification settings - Fork 0
Usage
What is needed to say about using a web page? Still, some instructions will follow:
If you really need a manual to use the web frontend, I obviously made something really wrong. But stop – what means "the" web frontend?
Actually, there are multiple "editions": HTML (for web browsers and eBook-readers like Aldiko), and OPDS (XML variant for eBook-readers like Moon+ Reader and FBReader). So how to call up which variant – or which URL to link or provide to others?
Switching between these formats is done via the URL parameter pageformat. Depending on its value, miniCalOPe displays the HTML- (pageformat=html) or OPDS-view (default, or pageformat=opds).
More URL parameters are automatically set by miniCalOPe when needed – and are currently not of interest so far as a "direct link" you figured out today may point somewhere else when you ran the scan script again (and did not use the merge mode there, so this completely emptied and refilled the database, and all IDs were re-assigned). See Permanent Links below on how to work around this.
There are different starting points using the catalog – but you can see that for yourself on its first page. Depending on his/her intention, a visitor may decide to list contents based on the authors name, the book title, or tags/genres. If I'm interested in a special area only (say: drama), it makes most sense to go via the tags/genres (as this automatically hides everything else). Am I interested in an author as versatile as e.g. Isaac Asimov, I'd better go with the authors list. And if I only happen to know the books title, or am interested in anything and can't decide yet – well, then I use the book list.
To keep things managable also on small screens (eBook reader, tablets, smartphones), miniCalOPe tries to only display the essential stuff (opposite to fill lists with verbose chatter). So complete details on a book you will not find before hitting its details page.
With each "non-merge scan" (see Merge-Mode below) tables in the database are truncated and refilled from the scratch, which means IDs are subject to change. So if you want to place a permanent link to a category, author, etc., you cannot do so using the common IDs. But instead you can use the name URL parameter in most cases: So e.g. http://server/opds/index.php?pageformat=html&prefix=tags&name=Adventure will link to the category/genre/tag named "Adventure" if you have such. If not, but there's some category containing this string (e.g. "Action+Adventure"), it will link to this. Exact matches come first, "relax" matches only if there is no exact match.
Content – in our case this means books. miniCalOPe currently supports them in multiple formats: ePub, Mobi, Fictionbook and PDF are available as-shipped, more formats can be added. In order for it to find the books, they have to be placed in a defined directory structure (except, of course, if you use Calibre as backend – in this case you can skip this step). Finally, the scan script has to run over those directories to fill the database with the required metadata – and everything should be ready for the above mentioned web frontend to work.
To make it easier, I start this off using an example:
<bookroot> -+- de -+- Abenteuer --+- Daniel Defoe -+- Robinson Crusoe.epub
| | | +- Robinson Crusoe.pdf
| | | +- Robinson Crusoe.desc
| | | +- Robinson Crusoe.jpg
| | +- Jules Verne -+- Reise um die Erde in 80 Tagen.epub
... ... ... ...
| +- Drama
| +- Humor
+- en -+- Adventure
+- Drama
+- Humour
Directly inside the $bookroot (see Configuration), the first directory level specifies the language of the book (you must use the 2-char-ISO-code, i.e. 'de' for German, 'en' for English, 'es' for Spanish, etc.). Next directory level specifies the tag/genre (spell it as it should be shown). The final directory level is the authors name – and into that directory come all the files for this author in this tag/genre and language. Take care to use only 7-bit alphanumeric characters (without special characters such as German Umlauts or French accents) plus characters as the minus (-) or underscore (_) to prevent possible trouble.
All files belonging to a book must share the same "first name" (i.e. only the file extension may differ). As you saw above, there can be multiple files for e.g. our Robinson Crusoe:
| File Extension | Description |
|---|---|
| epub | Our book in ePub format |
| fb2 | Our book in Fictionbook format |
| mobi | Our book in Mobipocket format |
| Our book in PDF format | |
| desc | text file with the description of our book (e.g. a summary, table of contents, etc.) The content of this file is displayed as-is – i.e. HTML-tags and line breaks are kept intact. You can even use basic HTML formatting, as long as opening and closing tags are on the same line. |
| data | Metadata for the book (see below) |
| jpg/png | Cover image – if both formats exist, only the *.jpg file will be used.The scan script tries to automatically extract cover images out of *.epub files if configured such and no cover image already exists. |
So there must be at least an *.epub or *.mobi file (or both; depending on your configuration) – all other files are optional.
Additional book metadata can be defined in files named <bookname>.data (i.e. the same name as the *.epub/*.mobi, just with the .data extension). Each line in this field has the syntax name::value – i.e. names and values are separated by double colons. The following names are available:
| Name | Example | Description |
|---|---|---|
| author | author::John Doe |
Author of the book. This can be used multiple times, in case multiple authors were involved in this book |
| isbn | isbn::123-12345-12345-5 |
ISBN of the book. This can also be the ISBN for the printed book, so one can find additional information using this. |
| publisher | publisher::Many Prints |
Publisher of this book |
| rating | rating::4 |
Rating of this book. Must be an integer between 1..5. Represents "stars given" – so the higher the better. |
| series | series::Book Collection |
collection a book belongs to (if there are multiple volumes) |
| series_index | series_index::3 |
The volume this book represents. With this examples, it would be "volume 3 of Book Collection" |
| tag | tag::Philosophy |
a tag for this book. You can specify multiple tags using multiple lines (see example below) |
| uri | uri::http://www.publisher.com/ |
Web URL for additional information (usually the publishers) |
Let's see some "real world example":
isbn::3-89965-118-9
author::Sebastian Boedeker
author::Oliver Moldenhauer
author::Benedikt Rubbel
tag::Computer
tag::Recht
In the doc/ subdirectory you can find a script named epubmeta, which extracts those data from EPUB files containing them. Simply pass it the name of the .epub file as parameter – and magically the corresponding .data, .desc and hopefully .jpg files will appear. You might need to polish them a little, though.
This can be found by the name scan.php within the installations main directory. When using multiple catalogs (with the advanced configuration), some precautions are necessary here as well – you find them exemplarily with the files scan_de.php and scan_en.php in the same place. Those are "wrappers" around scan.php – which they simply call after setting up the language to use.
Before you run any scan script, make sure to check your Configuration – a.o. to define whether to automatically extract covers from *.epub files. Afterwards: You should be able to run the appropriate scan script from the command line (using PHP CLI) – it has not been tested using a browser.
With the original mode ('rebuild') there was no problem to identify things: the database was emptied, and everything inserted anew. But this way it often happened that IDs changed, when a new entry was added "before".
Hence with version 1.7 a new scan mode was introduced: 'merge'. This tries to detect changes and keep IDs "intact". But how does it identify books?
- Path and file name (without extension, e.g.
Children/Robert Louis Stevenson/Treasure Island) are identical (the book was already there before, and still is in the same location) - if not found this way, but a book with the same file name (
Treasure Island) or book title ( thetitleattribute in the corresponding.datafile) was removed from its original location in the same run of the scan script (book was moved to a different category, or name of author has been corrected, of the file name changed, OR thetitleattribute updated)
So remember to not change to many things at the same time ;)