New calibre help file

[BetterRed]

Thanks BeccaPrice

re the buttons, my thought was to place them in a horizontal row at the top with no text - a'la the favourites button - which I was too scared to suggest - but just discovered

Its not important, now I know the buttons are there. I have a preference to have buttons, tabs, ribbons & bows at the top or down the sides of windows, reserving the bottom for status & error messages. I think it was Microsoft who started putting bars and buttons at the bottom of navigation panes - so we can blame them

By "when you've taken it as far as you intend' what I meant was when its out of the initial development phase and into maintenance phase.

Re glossary - Metadata Jacket - what's the reason for them, why would I want, or not want them, and where would I get them - I know I can delete them in the Modify Plugin.

Its all very well to document Process, but if the reader doesn't understand the purpose of the Data that's being processed then ... A common characteristic of a lot of technical documentation, is the assumption that the reader has in depth domain knowledge.

Becca - that's not a criticism of you in particular, but of the information industry in general.

<rant>The 'trick' is, when one writes/reviews a sentence in a "how to document", ask oneself "would someone who knew diddlysquat about this knowledge domain know the what, the where and the why of the object of that sentence". If not then define the object term in the Glossary, and put a reference to the definition in the sentence (hyperlink, whatever).</rant>

BR

[BeccaPrice]

"metadata jacket" - that's a good question. Can anyone who reads this answer, or shall I ask on the general calibre help forum? I don't think I referred to a metadata jacket in any of the procedures, but I'll certainly document it as soon as I get the information.

My purpose wasn't to re-create the user manual, which is wonderfully detailed and complete, but to create task-based procedures that answer the "why" as well as the "how".

When I was creating these procedures, the question "why would I want to do this" was foremost in my mind... that's why there are a collection of procedures in the Exercise portion: why would I want to create a custom column? to mark yes/no read, or to say what reading list something is on are two answers. There are a lot more types of custom columns, and I did give general instructions, but I also gave specific examples of two ways they could be used. In the introduction to all (most? there should be so, if I didn't) of the procedures, I tried to give situations in which the procedure would be done. I didn't document recipes yet, because I'm still answering for my self why one would want to create a recipe, and what are they used for? (I think the answer is to get news from specific sites or sources, and format that news and send it to your device on a regular basis - but the *how* to do it is more complex than I'm willing to get into here.)

[BeccaPrice]

By "when you've taken it as far as you intend' what I meant was when its out of the initial development phase and into maintenance phase.

That's pretty much where it is now. There will be some additions, as I get around to them, but the only one I've currently got on deck is dealing with multiple libraries. Send me a pm with your email, and I'll see whether I can email you a CHM version.

[theducks]

Originally Posted by BeccaPrice

"metadata jacket" - that's a good question. Can anyone who reads this answer, or shall I ask on the general calibre help forum? I don't think I referred to a metadata jacket in any of the procedures, but I'll certainly document it as soon as I get the information.

My purpose wasn't to re-create the user manual, which is wonderfully detailed and complete, but to create task-based procedures that answer the "why" as well as the "how".

When I was creating these procedures, the question "why would I want to do this" was foremost in my mind... that's why there are a collection of procedures in the Exercise portion: why would I want to create a custom column? to mark yes/no read, or to say what reading list something is on are two answers. There are a lot more types of custom columns, and I did give general instructions, but I also gave specific examples of two ways they could be used. In the introduction to all (most? there should be so, if I didn't) of the procedures, I tried to give situations in which the procedure would be done. I didn't document recipes yet, because I'm still answering for my self why one would want to create a recipe, and what are they used for? (I think the answer is to get news from specific sites or sources, and format that news and send it to your device on a regular basis - but the *how* to do it is more complex than I'm willing to get into here.)

Calibre can create a 'jacket' page,and yes it can contain all the regular (custom fields are not included without a hack )metadata that appears in the details pane
A 'jacket' is similar in many ways to a Dust Jacket fond on Hardbound books Front, Back and 2 flaps worth of stuff

[unboggling]

Originally Posted by BeccaPrice

"metadata jacket" - that's a good question. Can anyone who reads this answer, or shall I ask on the general calibre help forum?

Since BetterRed raised the question, maybe it'd be best to start a new thread with appropriate title and ask the question there.

Edit: but since theducks replied here I'll add this:

I'm not suggesting Becca include this topic, and I don't recommend including it because it is merely one of hundreds of other small things, but FYI:

From Help, kiwidude's Quality Check plugin:

A “jacket” is a calibre generated file inserted into an ePub during conversion that contains a summary of the book such as ttile, authors, rating and description. You can enable this in the conversion options under Structure Detection -> Insert metadata as start of book.

From Help, kiwidude's Modify ePub plugin:

Remove any calibre generated jackets listing book metadata such as title, authors, comments and rating. Jackets removed are both those from the latest versions of calibre, and those “legacy” jackets generated using versions of calibre prior to 0.6.50. The “newer” jackets are able to be identified by a metadata tag in the xhtml.
Use this option if you do not want jackets in your books.

From Preferences, Conversion, Common Options, Structure Detection,
Thumbtip for Checkbox, Insert metadata as page at start of book:

...This is useful if your ebook reader does not support displaying/searching metadata directly.

[BeccaPrice]

so when I include metadata like a book description and the tags for the book at the beginning of the book file, that's a metadata jacket. I see. I've got the procedure written - I just need to explain what it is more clearly.

metadata that's included in the "jacket" are things like the material that's in the comments field, the tags, and the publication data - anything else?

[unboggling]

Originally Posted by BeccaPrice

so when I include metadata like a book description and the tags for the book at the beginning of the book file, that's a metadata jacket. I see. I've got the procedure written - I just need to explain what it is more clearly.

metadata that's included in the "jacket" are things like the material that's in the comments field, the tags, and the publication data - anything else?

title, series, series index, author, publisher, pubdate, tags, comments

I hadn't been using it. The jacket's appearance looks better now than it did last year.

[BetterRed]

My question was within the context of what should be in a Glossary of Terms. I would not expect a GoT to tell me how to do things to a given object, Regarding metadata jackets I asked

what's the reason for them,
why would I want, or not want them,
where would I get them

So when I tick this in the Structure Detection sub-dialogue of the Conversion Dialogue - am I creating the digital equivalent of a Book Title Page or a Book Dust Jacket

In the Real Book world I would have thought that the Title Page and Dust Cover are two very different artefacts, with quite different purposes

If in the eBook world a Title Page and a Metadata Jacket are one and the same, then why have two terms, other than to confuse us non-aficionados. It wouldn't be the first time that's happened in the IT malaise.

My English teacher once made me write out in copperplate, in india ink, in my exercise book, the following maxim "I shall use not different words with the same meaning, nor yet the same word with different meanings" 100 times

BR

[BeccaPrice]

The introduction to that section now reads:

calibre has a conversion option to insert the book metadata as a "jacket" at the start of the book.

It's called a "jacket" because the metadata included at the start of the book is like a hardback's dust jacket, or the back cover of a paperback. The information it contains is (in order): title, series, series index, author, publisher, pubdate, tags, comments.

is this better? it's not a replacement (or restatement) of the title page, it's additional material that is placed at the beginning of the ebook file.