From e7cc30b3a9836035c0cbda4ceae8e140666168b2 Mon Sep 17 00:00:00 2001
From: un-pogaz <46523284+un-pogaz@users.noreply.github.com>
Date: Sun, 16 Oct 2022 15:01:39 +0200
Subject: [PATCH] add doc

---
 manual/template_lang.rst                    | 3 +++
 src/calibre/gui2/dialogs/template_dialog.py | 1 +
 2 files changed, 4 insertions(+)

diff --git a/manual/template_lang.rst b/manual/template_lang.rst
index f37d45859f..64add7f1e2 100644
--- a/manual/template_lang.rst
+++ b/manual/template_lang.rst
@@ -661,6 +661,7 @@ A PTM template begins with:
      # db: a calibre legacy database object
      # globals: the template global variable dictionary
      # arguments: is a list of arguments if the template is called by a GPM template, otherwise None
+     # funcs: allows to use the Builtin/User functions and Stored GPM/Python templates
 
      # your Python code goes here
      return 'a string'
@@ -669,6 +670,8 @@ You can add the above text to your template using the context menu, usually acce
 
 The context object supports ``str(context)`` that returns a string of the context's contents, and ``context.attributes`` that returns a list of the attribute names in the context.
 
+The ``context.funcs`` attribute allows to use the Builtin and User functions, and also the Stored GPM/Python templates so that you can exectute them directly in your code. The functions can be retrieve by they name and they name plus a '_' at the end in case of conflict with Python language keywords. Note that all functions will return a string value, only the special functions ``arguments()``, ``globals()`` and ``set_globals()`` will return a dict based on the passed keywords arguments.
+
 Here is an example of a PTM template that produces a list of all the authors for a series. The list is stored in a `Column built from other columns, behaves like tags`. It shows in :guilabel:`Book details` and has the :guilabel:`on separate lines` checked (in :guilabel:`Preferences->Look & feel->Book details`). That option requires the list to be comma-separated. To satisfy that requirement the template converts commas in author names to semicolons then builds a comma-separated list of authors. The authors are then sorted, which is why the template uses author_sort.
 
 .. code-block:: python
diff --git a/src/calibre/gui2/dialogs/template_dialog.py b/src/calibre/gui2/dialogs/template_dialog.py
index 2275192b36..f1e85315ed 100644
--- a/src/calibre/gui2/dialogs/template_dialog.py
+++ b/src/calibre/gui2/dialogs/template_dialog.py
@@ -593,6 +593,7 @@ def evaluate(book, context):
     # db: a calibre legacy database object
     # globals: the template global variable dictionary
     # arguments: is a list of arguments if the template is called by a GPM template, otherwise None
+    # funcs: allows to use the Builtin/User functions and Stored GPM/Python templates
 
     # your Python code goes here
     return 'a string'