1) change the author sep character in plugboards to '&', because the '|' conflicts with template fields

2) permit both functions and format strings
3) Updates to the FAQ

src/calibre/ebooks/metadata/book/base.py

@@ -316,7 +316,7 @@ class Metadata(object):
                 if dest == 'tags':
                     self.set(dest, [f.strip() for f in val.split(',') if f.strip()])
                 elif dest == 'authors':
-                    self.set(dest, [f.strip() for f in val.split('|') if f.strip()])
+                    self.set(dest, [f.strip() for f in val.split('&') if f.strip()])
                 else:
                     self.set(dest, val)
             except:

src/calibre/manual/template_lang.rst

@@ -9,7 +9,7 @@ The |app| template language
 The |app| template language is used in various places. It is used to control the folder structure and file name when saving files from the |app| library to the disk or eBook reader.
 It is also used to define "virtual" columns that contain data from other columns and so on.
 
-The basic template language is very simple, but has very powerful advanced features. The basic idea is that a template consists of names in curly brackets that are then replaced by the corresponding metadata from the book being processed. So, for example, the default template used for saving books to device in |app| is::
+The basic template language is very simple, but has very powerful advanced features. The basic idea is that a template consists of text and names in curly brackets that are then replaced by the corresponding metadata from the book being processed. So, for example, the default template used for saving books to device in |app| is::
 
     {author_sort}/{title}/{title} - {authors}
 
@@ -17,6 +17,14 @@ For the book "The Foundation" by "Isaac Asimov" it will become::
 
     Asimov, Isaac/The Foundation/The Foundation - Isaac Asimov
 
+The slashes are text, which is put into the template where it appears. For example, if your template is::
+
+    {author_sort} Some Important Text {title}/{title} - {authors}
+
+For the book "The Foundation" by "Isaac Asimov" it will become::
+
+    Asimov, Isaac Some Important Text The Foundation/The Foundation - Isaac Asimov
+    
 You can use all the various metadata fields available in calibre in a template, including any custom columns you have created yourself. To find out the template name for a column simply hover your mouse over the column header. Names for custom fields (columns you have created yourself) always have a # as the first character. For series type custom fields, there is always an additional field named ``#seriesname_index`` that becomes the series index for that series. So if you have a custom series field named ``#myseries``, there will also be a field named ``#myseries_index``.
 
 In addition to the column based fields, you also can use::
@@ -96,7 +104,9 @@ Using functions in templates
 
 Suppose you want to display the value of a field in upper case, when that field is normally in title case. You can do this (and many more things) using the functions available for templates. For example, to display the title in upper case, use ``{title:uppercase()}``. To display it in title case, use ``{title:titlecase()}``.
 
-Function references replace the formatting specification, going after the : and before the first ``|`` or the closing ``}``. Functions must always end with ``()``. Some functions take extra values (arguments), and these go inside the ``()``.
+Function references appear in the format part, going after the ``:`` and before the first ``|`` or the closing ``}``. If you have both a format and a function reference, the function comes after another ``:``. Functions must always end with ``()``. Some functions take extra values (arguments), and these go inside the ``()``. 
+
+Functions are always applied before format specifications. See further down for an example of using both a format and a function, where this order is demonstrated.
 
 The syntax for using functions is ``{field:function(arguments)}``, or ``{field:function(arguments)|prefix|suffix}``. Argument values cannot contain a comma, because it is used to separate arguments. The last (or only) argument cannot contain a closing parenthesis ( ')' ). Functions return the value of the field used in the template, suitably modified.
 
@@ -113,6 +123,16 @@ The functions available are:
     * ``lookup(field if not empty, field if empty)`` -- like test, except the arguments are field (metadata) names, not text. The value of the appropriate field will be fetched and used. Note that because composite columns are fields, you can use this function in one composite field to use the value of some other composite field. This is extremely useful when constructing variable save paths (more later).
     * ``re(pattern, replacement)`` -- return the field after applying the regular expression. All instances of `pattern` are replaced with `replacement`. As in all of |app|, these are python-compatible regular expressions.
 
+Now, about using functions and formatting in the same field. Suppose you have an integer custom column called ``#myint`` that you want to see with leading zeros, as in ``003``. To do this, you would use a format of ``0>3s``. However, by default, if a number (integer or float) equals zero then the field produces the empty value, so zero values will produce nothing, not ``000``. If you really want to see ``000`` values, then you use both the format string and the ``ifempty`` function to change the empty value back to a zero. The field reference would be::
+
+    {#myint:0>3s:ifempty(0)}
+    
+Note that you can use the prefix and suffix as well. If you want the number to appear as ``[003]`` or ``[000]``, then use the field::
+
+    {#myint:0>3s:ifempty(0)|[|]}
+    
+
+    
 Special notes for save/send templates
 -------------------------------------
 
@@ -124,11 +144,35 @@ For example, assume we want the folder structure `series/series_index - title`,
 
 The slash and the hyphen appear only if series is not empty.
 
-The lookup function lets us do even fancier processing. For example, assume we want the following: if a book has a series, then we want the folder structure `series/series index - title.fmt`. If the book does not have a series, then we want the folder structure `genre/author_sort/title.fmt`. If the book has no genre, use 'Unknown'. We want two completely different paths, depending on the value of series.
+The lookup function lets us do even fancier processing. For example, assume that if a book has a series, then we want the folder structure `series/series index - title.fmt`. If the book does not have a series, then we want the folder structure `genre/author_sort/title.fmt`. If the book has no genre, we want to use 'Unknown'. We want two completely different paths, depending on the value of series.
 
 To accomplish this, we:
-    1. Create a composite field (call it AA) containing ``{series:||}/{series_index} - {title'}``. If the series is not empty, then this template will produce `series/series_index - title`.
+    1. Create a composite field (call it AA) containing ``{series}/{series_index} - {title'}``. If the series is not empty, then this template will produce `series/series_index - title`.
     2. Create a composite field (call it BB) containing ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. This template produces `genre/author_sort/title`, where an empty genre is replaced wuth `Unknown`.
     3. Set the save template to ``{series:lookup(AA,BB)}``. This template chooses composite field AA if series is not empty, and composite field BB if series is empty. We therefore have two completely different save paths, depending on whether or not `series` is empty.
 
+Templates and Plugboards
+------------------------
+
+Plugboards are used for changing the metadata written into books during send-to-device and save-to-disk operations. A plugboard permits you to specify a template to provide the data to write into the book's metadata. You can use plugboards to modify the following fields: authors, author_sort, language, publisher, tags, title, title_sort. This feature should help those of you who want to use different metadata in your books on devices to solve sorting or display issues.
+
+When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, save_to_disk, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are `connected` to their destination fields, hence the name `plugboards`. You can, of course, use composite columns in these templates. 
+
+The tags and authors fields have special treatment, because both of these fields can hold more than one item. After all, book can have many tags and many authors. When you specify that one of these two fields is to be changed, the result of evaluating the template is examined to see if more than one item is there.
+
+For tags, the result cut apart whereever |app| finds a comma. For example, if the template produces the value ``Thriller, Horror``, then the result will be two tags, ``Thriller`` and ``Horror``. There is no way to put a comma in the middle of a tag.
+
+The same thing happens for authors, but using a different character for the cut, a `&` (ampersand) instead of a comma. For example, if the template produces the value ``Blogs, Joe&Posts, Susan``, then the book will end up with two authors, ``Blogs, Joe`` and ``Posts, Susan``. If the template produces the value ``Blogs, Joe;Posts, Susan``, then the book will have one author with a rather strange name.
+
+Plugboards affect only the metadata written into the book. They do not affect calibre's metadata or the metadata used in ``save to disk`` and ``send to device`` templates. Plugboards also do not affect what is written into a Sony's database, so cannot be used for altering the metadata shown on a Sony's menu.
+
+Helpful Tips
+------------
+
+You might find the following tips useful.
+
+    * Create a custom composite column to test templates. Once you have the column, you can change its template simply by double-clicking on the column. Hide the column when you are not testing.
+    * Templates can use other templates by referencing a composite custom column.
+    * In a plugboard, you can set a field to empty (or whatever is equivalent to empty) by using the special template ``{null}``. This template will always evaluate to an empty string.
+    * The technique described above to show numbers even if they have a zero value works with the standard field series_index.
     

src/calibre/utils/formatter.py

@@ -93,8 +93,17 @@ class TemplateFormatter(string.Formatter):
 
         # Handle functions
         p = fmt.find('(')
-        if p >= 0 and fmt[-1] == ')' and fmt[0:p] in self.functions:
-            field = fmt[0:p]
+        dispfmt = fmt
+        if p >= 0 and fmt[-1] == ')':
+            colon = fmt[0:p].find(':')
+            if colon < 0:
+                dispfmt = ''
+                colon = 0
+            else:
+                dispfmt = fmt[0:colon]
+                colon += 1
+            if fmt[colon:p] in self.functions:
+                field = fmt[colon:p]
                 func = self.functions[field]
                 args = fmt[p+1:-1].split(',')
                 if (func[0] == 0 and (len(args) != 1 or args[0])) or \
@@ -104,8 +113,8 @@ class TemplateFormatter(string.Formatter):
                     val = func[1](self, val)
                 else:
                     val = func[1](self, val, *args)
-        elif val:
-            val = string.Formatter.format_field(self, val, fmt)
+        if val:
+            val = string.Formatter.format_field(self, val, dispfmt)
         if not val:
             return ''
         return prefix + val + suffix