EPUB metadata used by Calibre

[WimmeR]

Hello,

I have created an EPUB that is part of a series. I have put

<meta content="Series Name" name="calibre:series" />
<meta content="1" name="calibre:series_index" />

in the content.opf file of the EPUB.

When I add the book, calibre correctly parses this data and it appears in the metadata. I tried to do the same with the creation date and the publication date but it doesn't work. I googled for calibre metadata but everytime I get explanations on how to use the metadata editor which is not what I want. I want to create an EPUB that can be added to the calibre library including the correct metadata.
I then downloaded the complete source code of calibre and found "calibre:series_index" in opf2.py. In that same file I found references to pubdate_path (which apparently uses a "date" tag) and timestamp.
I used the date tag and the timestamp tag using the dc and calibre namespaces, but every time I add the book, calibre insists on putting today's date in Date, Published and Modified.

Can someone please explain which metadata tags from the EPUB are processed by calibre and where I have to put them in the EPUB so that calibre can find them?

Thanks
-=Wim=-

[kovidgoyal]

Just set some distinctive values for your desired metadata in calibre then save an epub to disk, open it up and see how calibre saves the metadata fields you are interested in.

[eschwartz]

Here is an example content.opf from a book in my library (see attachment). It appears to be using:

<meta name="calibre:timestamp" content="2013-01-20T05:45:35+00:00"/>

to correspond to calibre's "Date" field, and:

<dc:date>2003-01-02T00:00:00+00:00</dc:date>

to correspond to calibre's "Published" field.

[eschwartz]

I am pretty sure calibre will insist on putting the current datetime in as "Date" which represents the date added to calibre, unless you import the book SAVE, not just the book. Since that will usually include calibre's metadata.opf, it will set all metadata according to the metadata.opf, including the Added-to-calibre datetime.

[WimmeR]

So I edited the metadata of a book (I put 2008-10-12 in the date field and 2010-12-14 in the published field), opened metadata.opf from the book folder and found these:

<dc:date>2010-12-13T23:00:00+00:00</dc:date>
<meta content="2008-10-11T22:00:00+00:00" name="calibre:timestamp"/>

So the "date" field has the "calibre:timestamp" tag and the "published" field has the "dc:date" tag, as eschwartz already pointed out.
Next, I put

<meta content="2010-12-13T23:00:00+00:00" name="dc:date" />
<meta content="2008-10-11T22:00:00+00:00" name="calibre:timestamp" />

in the content.opf file of the EPUB.
I remove the book from the calibre library, and add the modified one.
In the metadata.opf file I find:

<dc:date>2014-04-08T22:00:00+00:00</dc:date>
<meta content="2014-04-09T09:39:48.364000+00:00" name="calibre:timestamp"/>

which is not what I've put in.

Observations:
1) calibre does not interpret the content.opf file of the EPUB correctly.
2) calibre uses different rules for the timezone (I'm in UTC+2).
If I enter 2008-10-12 in the DATE field in the UI, calibre subtracts 2 hours
If I enter 2010-12-14 in the PUBLISHED field, calibre subtracts 1 hour
Apart from the fact that it is nonsense to store a published date with a time part, the rules must be the same.
3) The date field is saved in a different format: the result of editing in the UI saves the date up to seconds (without fractional part) while when adding a book, the date is saved up to 1 millionth of a second.

(let's not get distracted by observations 2 and 3, the real problem is observation 1)

-=Wim=-

[kovidgoyal]

I have no idea what you are doing.

1) <dc:date> is used for the published date

2) You cannot control the date field via the OPF since the date field always shows the date the book was added to calibre regardless of the value of calibre:timestamp

It is nonsense to not put a time into a timestamp field. When you put in only a date what you are actually doing is saying the date is what you say it is +- 1 day depending on which timezone the person interpreting the date is in. Not to mentiont hat plenty of publications can have intra day publication dates.

[WimmeR]

Originally Posted by kovidgoyal

I have no idea what you are doing.

I'm sorry, I'll try to give some more context. I created an EPUB with Sigil. In the metadata editor of Sigil I saw 3 dates: Date:Creation, Date:Modification and Date:Publication. In the book list of calibre I also see 3 dates: Date, Published and Modified. I assumed that these dates meant the same in both applications (I now know they don't). What I tried to do was to get calibre "read" the dates of the EPUB, so that I didn't have to modify them afterwards in calibre.

Originally Posted by kovidgoyal

1) <dc:date> is used for the published date

Yes. But if I have a book that was published say in 2010 and I add it in calibre, why does the Published column show today's date?
I figured I did something wrong with the metadata in the EPUB so basically, that was my initial question: which tag do I have to use in the contents.opf of the EPUB so that calibre can recognise it?

Originally Posted by kovidgoyal

2) You cannot control the date field via the OPF since the date field always shows the date the book was added to calibre regardless of the value of calibre:timestamp

Ok, I didn't know that. I (wrongfully) thought that the date field was the created date (i.e. the date that the EPUB was first created, analogous to the created date of a file on a filesystem).

Originally Posted by kovidgoyal

It is nonsense to not put a time into a timestamp field. When you put in only a date what you are actually doing is saying the date is what you say it is +- 1 day depending on which timezone the person interpreting the date is in.

Right, BUT: in the metadata editor of calibre, you cannot enter a time in the date or published field. You therefore should assume that the time is 00:00:00+00:00 and not compensate for timezone differences when saving.
Assume a book was published on christmas and I would enter 2013-12-25 (remember I'm in time zone +2). I then take my library (which is on a thumb drive) and I open it on a computer in London (UTC) then all of a sudden the book *appears* to be published the day before christmas.
What I want to say is that IMHO a publication date is a fixed date, regardless in which timezone you look at it.
I don't want to be pedantic, but Dublin Core says that dc:date follows the YYYY-MM-DD format (see point 4.12. of http://dublincore.org/documents/usag...elements.shtml). The time part is not present.

Originally Posted by kovidgoyal

Not to mentiont hat plenty of publications can have intra day publication dates.

I'm not sure I understand. Do you mean that the same publication is published multiple times the same day?

-=Wim=-

[BetterRed]

@WimmeR - You can control the format of the 3 dates that calibre keeps, including the inclusion of time, via Preferences->Tweaks->Control how dates are displayed

Originally Posted by WimmeR

I'm not sure I understand. Do you mean that the same publication is published multiple times the same day?

News agencies etc often update their news reports to correct errors, this is usually indicated in the news reports dateline and a note at the bottom. So yes the same 'book' can be published multiple times on the same day.

Originally Posted by WimmeR

Assume a book was published on christmas and I would enter 2013-12-25 (remember I'm in time zone +2). I then take my library (which is on a thumb drive) and I open it on a computer in London (UTC) then all of a sudden the book *appears* to be published the day before christmas

I agree with you, the published date/time that I see in calibre should be the wall date & time at the place where the event happened (book published, news report filed etc), it should have nothing to do with the time setting on the computer I happen to be using.

I'm not so bothered by date/time the book was added to calibre (timestamp), and even less by calibre's modified date because it can change 'unexpectedly'

BR