What does this mean?

[BeccaPrice]

I blindly copied a plugboard rule I saw somewhere here to my copy of Calibre - it's supposed to put the series name and number after the title. The couple of times I've used it, it seems to work very well. But now I have to teach someone else how to use it, and I'd like to understand the parts of the rule, and what it is I'm typing.

So, can someone put the following into English? Thanks!

mobi:any device = ([{title} {series:|(| }{series_index:0>2s||)}] -> title)


(I have the same rule only for epub, for books I load on my Sony 350)

[Synamon]

This tutorial explains template language.

[BeccaPrice]

Thank you.

[chaley]

My understanding from your other posts is that you are writing documentation for calibre. You will include the template language? Wonderful!

I am the author of the calibre template stuff (template language, plugboards, custom columns, etc), and am happy to answer your questions. Feel free to post them in this thread, as I am sure that others will have similar questions and benefit from the discussion. Also feel free to tell me that an answer is incomprehensible. It has been so long since I started playing with computer languages and interpreters (almost 40 years) that I forget what other people might not know.

[BeccaPrice]

Well, I'm doing this for a class project - and I'm not a programmer - so I'm going to need all the help I can get, Chaley - and thanks for the offer.

I read the tutorial, and I'm still confused. (is the template language based on python?) We're not going to include a lot of the template stuff in our document, only how to rename books with series and series number in it, but I would like to explain how the rule was constructed.

at another thread (
https://www.mobileread.com/forums/sho...60#post1926660) someone else posted the following rule:

{series}{series_index:| - | - }{title}

That does the same thing that my rule does, only in a slightly different order, and makes perfect sense to me although I'm not sure what the pipes and dashes mean. But it's a much simpler rule than mine has all the different kinds of brackets and such.

Chaley, would you be willing to put it into English for me? Thanks so very much.

[HarryT]

Becca, this is clearly explained in the tutorial that was linked to earlier:

There are cases where you might want to have text appear in the output only if a field is not empty. A common case is series and series_index, where you want either nothing or the two values with a hyphen between them. Calibre handles this case using a special field syntax.

For example, assume you want to use the template:

{series} - {series_index} - {title}

If the book has no series, the answer will be - - title. Many people would rather the result be simply title, without the hyphens. To do this, use the extended syntax {field:|prefix_text|suffix_text}. When you use this syntax, if field has the value SERIES then the result will be prefix_textSERIESsuffix_text. If field has no value, then the result will be the empty string (nothing); the prefix and suffix are ignored. The prefix and suffix can contain blanks.

Using this syntax, we can solve the above series problem with the template:

{series}{series_index:| - | - }{title}

The hyphens will be included only if the book has a series index, which it will have only if it has a series.

Notes: you must include the : character if you want to use a prefix or a suffix. You must either use no | characters or both of them; using one, as in {field:| - }, is not allowed. It is OK not to provide any text for one side or the other, such as in {series:|| - }. Using {title:||} is the same as using {title}.

If you can clarify which part of this you're having trouble with, I'll be happy to explain further.

[theducks]

Originally Posted by BeccaPrice

Well, I'm doing this for a class project - and I'm not a programmer - so I'm going to need all the help I can get, Chaley - and thanks for the offer.

I read the tutorial, and I'm still confused. (is the template language based on python?) We're not going to include a lot of the template stuff in our document, only how to rename books with series and series number in it, but I would like to explain how the rule was constructed.

at another thread (
https://www.mobileread.com/forums/sho...60#post1926660) someone else posted the following rule:

{series}{series_index:| - | - }{title}

That does the same thing that my rule does, only in a slightly different order, and makes perfect sense to me although I'm not sure what the pipes and dashes mean. But it's a much simpler rule than mine has all the different kinds of brackets and such.

Chaley, would you be willing to put it into English for me? Thanks so very much.

I'll take a stab at it:
{} are a standard (listed) field/column name (you can't see Author_sort, series and series_index are shown concatenated...)
Pipes are "If-then-else" constructs that place the literal between in the relative position.

series_-_series_index_-_Title (NB I uses orange Underscores to show the spaces used in the template)

a slash (/) creates another folder inside

Here is a template I used on my reader (now, more complex and automates series treatment) that used filenames only in the book chooser, that shows the use of Literals and mixed in with field valued :

00NoSeries/{author_sort[0]}_authors/{authors}/{title}-{id}

00NoSeries is simply a folder I used to keep any book that did not belong to a series (stand alone books)

{author_sort[0]}_authors made a folder inside the above for the first initial of the Authors Last Name (my authors show Fn Ln): Mark Twain would create: Authors_T

{title}-{id} makes the book folder, showing the Calibre Library ID (simply there to help me spot duplicate or Alternate versions)

This was all done before Plug boards and programmatic templates

[BeccaPrice]

using my rule, as an example of what I don't understand (please remember that I am not a programmer, and this stuff is very new to me)

([{title} {series:|(| }{series_index:0>2s||)}] -> title)

The whole rule is included in opening and closing parens (but why isn't the second rule I cited enclosed in parens?)

I have the title of the book {title} in the metadata. If there is a series name, it goes next in a paren (do the pipes indicate a literal paren rather than the paren being used as part of the syntax?). that's the {series:|()} part.

next comes the series number. That's the {series_index:0>2s||)} part.

what does the 0>2s mean? I assume that it's saying that the series index has to be greater than 0, but I don't understand the 2s part.

and if I'm right that the pipes indicate a literal paren, shouldn't it be |)| rather than ||)?

and I'm not sure what the -> title part means, since the title of the book is included in the first statement.

Thanks!

[HarryT]

Originally Posted by theducks

{author_sort[0]}_authors made a folder inside the above for the first initial of the Authors Last Name (my authors show Fn Ln): Mark Twain would create: Authors_T

An exceedingly minor correction, Ducks: it will actually create "T_authors", not "Authors_T", will it not?

[theducks]

I don't use the plug board with its paren rules or a device that only allow a title

the 02s says make the series number 2 digits and pad with leading 0's if there is only 1 digit: 07 23

[BeccaPrice]

but it's not 02s, it's 0>2s - what is the greater-than sign for?

let's say i want the series name first,number, and then title of the book. would the rule then read:

mobi:any device = ([{series:|(| }{series_index:0>2s||)}{title}] -> title)

and I'm not sure what the last ->title means, or why it's out of the square brackets.

[HarryT]

Originally Posted by BeccaPrice

but it's not 02s, it's 0>2s - what is the greater-than sign for?

let's say i want the series name first,number, and then title of the book. would the rule then read:

mobi:any device = ([{series:|(| }{series_index:0>2s||)}{title}] -> title)

and I'm not sure what the last ->title means, or why it's out of the square brackets.

Firstly, the "-> title" isn't a part of the rule. If you look at how you define a metadata plugboard, there are three parts to it: the format/device, the rule itself, and which metadata field the result should be sent to. The "-> title" is just a way of saying "place the output in the title field". It's not a part of the rule. Look at how you enter a plugboard in Calibre, and it'll become clear.

The "0>2s" is a Python formatting description and means:

0: Use a "0" as a fill character.
>: Right align the output in the available space.
2: Make the field 2 characters wide.
s: Display the result as a string.

Given that there's a fill character, the ">" is, in fact, redundant. Had there not been a fill character, though, it makes, say, a "7" display as " 7" rather than as "7 ".

Hope this helps.

[chaley]

(After writing this reply I found that HarryT had answered the question far more succinctly, but having gone to the trouble to write this, I posted it.)

First comment: the template language is not python, and is only loosely related to python. It does use some python things such as formatting (see below), but that was for my convenience. It might help to think of the template language as serving a similar purpose in calibre as formula functions serve in Excel; they permit customization without having to change the underlying program.

Regarding:

Originally Posted by BeccaPrice

I blindly copied a plugboard rule I saw somewhere here to my copy of Calibre - it's supposed to put the series name and number after the title.
...
mobi:any device = ([{title} {series:|(| }{series_index:0>2s||)}] -> title)

and

Originally Posted by BeccaPrice

using my rule, as an example of what I don't understand (please remember that I am not a programmer, and this stuff is very new to me)

([{title} {series:|(| }{series_index:0>2s||)}] -> title)

The whole rule is included in opening and closing parens (but why isn't the second rule I cited enclosed in parens?)

First thing to remember: a plugboard is not the same thing as a template. A plugboard *uses* templates.

Your first example describes a plugboard containing one template that changes the title field. Such descriptions have a fixed format. The template plus changed field are between parentheses. The changed field is separated from the template by the characters "->". The template is contained within "[]" characters. In other words, the syntax is:

format:device = ([TEMPLATE] -> CHANGED FIELD)

where (...) is repeated for each changed field in the plugboard.

Your example says that when a "mobi" format is sent to "any device", then the template

{title} {series:|(| }{series_index:0>2s||)}

is evaluated and the result is placed into the title metadata inside the book.

what does the 0>2s mean? I assume that it's saying that the series index has to be greater than 0, but I don't understand the 2s part.

This is telling the template language processor how to format the series index. The initial 0 means add zeros to the front if needed. The > means align the result to the right side (important for what comes next). The 2 means that the field should be 2 long, and the 's' means it is a string. The combination of all of this is "make series_index a value 2-long, left filled with zero characters as needed. Example: 1 -> 01. 5 -> 05. 10 -> 10.

See http://docs.python.org/library/string.html#formatspec for more than you ever wanted to know about formatting.

[BeccaPrice]

This helps a lot, HarryT!

The problem was, I didn't enter the rule, really. I just copy/pasted from something I saw somewhere else. I did it blindly rather than understanding what I was doing.

What would the syntax be if I wanted the output to be:

Vorkosigan - 01 - Shards of Honor

instead of the current

Shards of Honor (Vorkosigan 01)?

I have

{series} - {series_index} - {title}

from someone else, but I want the series to be 01 rather than 1 (some of my series are quite long).

[HarryT]

Use:

{series}{series_index:0>2s| - | - }{title}

The problem with your version is that you'll get the hyphens appended to the title even if the book isn't in a series.

What I use personally is:

{series:|| }{series_index:0>2s|| - }{title}

Which, in your example, would give:

Vorkosigan 01 - Shards of Honor