Merge from trunk

setup/installer/__init__.py

@@ -123,7 +123,7 @@ class VMInstaller(Command):
         subprocess.check_call(['scp',
             self.VM_NAME+':build/calibre/'+installer, 'dist'])
         if not os.path.exists(installer):
-            self.warn('Failed to download installer')
+            self.warn('Failed to download installer: '+installer)
             raise SystemExit(1)
 
     def clean(self):

src/calibre/manual/faq.rst

@@ -280,7 +280,7 @@ Why doesn't |app| have a column for foo?
 |app| is designed to have columns for the most frequently and widely used fields. In addition, you can add any columns you like. Columns can be added via :guilabel:`Preferences->Interface->Add your own columns`.
 Watch the tutorial `UI Power tips <http://calibre-ebook.com/demo#tutorials>`_ to learn how to create your own columns.
 
-You can also create "virtual columns" that contain combinations of the metadata from other columns. In the add column dialog choose the option "Column from other columns" and in the template enter the other column names. For example to create a virtual column containing formats or ISBN, enter ``{formats}`` for formats or ``{isbn}`` for ISBN.
+You can also create "virtual columns" that contain combinations of the metadata from other columns. In the add column dialog choose the option "Column from other columns" and in the template enter the other column names. For example to create a virtual column containing formats or ISBN, enter ``{formats}`` for formats or ``{isbn}`` for ISBN. For more details, see :ref:`templatelangcalibre`.
 
 
 Can I have a column showing the formats or the ISBN?

src/calibre/manual/gui.rst

@@ -84,6 +84,9 @@ Send to device
     1. **Send to main memory**: The selected books are transferred to the main memory of the ebook reader.
     2. **Send to card**: The selected books are transferred to the storage card on the ebook reader.
 
+You can control the file name and folder structure of files sent to the device by setting up a template in
+:guilabel:`Preferences->Import/Export->Sending books to devices`. Also see :ref:`templatelangcalibre`.
+
 .. _save_to_disk:
 
 Save to disk
@@ -108,6 +111,10 @@ All available formats as well as metadata is stored to disk for each selected bo
 
 Saved books can be re-imported to the library without any loss of information by using the :ref:`Add books <add_books>` action.
 
+You can control the file name and folder structure of files saved to disk by setting up a template in
+:guilabel:`Preferences->Import/Export->Saving books to disk`. Also see :ref:`templatelangcalibre`.
+
+
 .. _fetch_news:
 
 Fetch news

src/calibre/manual/index.rst

@@ -39,4 +39,10 @@ Sections
    develop
    glossary
 
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   template_lang
+   portable
 

src/calibre/manual/template_lang.rst

@@ -0,0 +1,61 @@
+
+.. include:: global.rst
+
+.. _templatelangcalibre:
+
+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 used to define "virtual" columns that contain data from other columns and so on.
+
+In essence, the template language is very simple. 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::
+
+    {author_sort}/{title}/{title} - {authors}
+
+For the book "The Foundation" by "Isaac Asimov" it will become::
+
+    Asimov, Isaac/The Foundation/The Foundation - Isaac Asimov
+
+You can use all the various metadata fields available in calibre in a template, including the custom columns you have created yourself. To find out the template name for a column sinply hover your mouse over the column header. Names for custom fields (columns you have created yourself) are always prefixed by an #. For series type fields, there is always an additional field named ``series_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::
+
+    {formats} - A list of formats available in the |app| library for a book
+    {isbn}    - The ISBN number of the book
+
+If a particular book does not have a particular piece of metadata, the field in the template is automatically removed for that book. So for example::
+
+    {author_sort}/{series}/{title} {series_index}
+
+will become::
+
+    {Asimov, Isaac}/Foundation/Second Foundation - 3
+
+and if a book does not have a series::
+
+    {Asimov, Isaac}/Second Foundation
+
+(|app| automatically removes multiple slashes and leading or trailing spaces).
+
+
+Advanced formatting
+----------------------
+
+You can do more than just simple substitution with the templates. You can also control how the substituted data is formatted. For instance, suppose you wanted to ensure that the series_index is always formatted as three digits with leading zeros. This would do the trick::
+
+    {series_index:0>3s} - Three digits with leading zeros
+
+If instead of leading zeros you want leading spaces, use::
+
+   {series_index:>3s} - Thre digits with leading spaces
+
+For trailing zeros, use::
+
+   {series_index:0<3s} - Three digits with trailing zeros
+
+
+If you want only the first two letters of the data to be rendered, use::
+
+   {author_sort:.2} - Only the first two letter of the author sort name
+
+The |app| template language comes from python and for more details on the syntax of these advanced formatting operations, look at the `Python documentation <http://docs.python.org/library/string.html#format-string-syntax>`_.
+