Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-09 03:04:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Several changes:

Browse Source 
- As requested, document_to_rst() now takes an indent. It also takes a prefix in case the RST is a list item.
- Fixes to escaping when generating HTML.
- Change the documentation in formatter_functions.py to use 'r' strings, as discussed.
- Fixes to the new DocViewer class.
- Show stored templates and user template functions in DocViewer.

This commit contains un_pogaz's changes (I think).
This commit is contained in:
Charles Haley 2024-11-11 12:26:17 +00:00
parent 7ecc30663f
commit bf488a43a8
4 changed files with 176 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
src/calibre/gui2/dialogs/template_dialog.py
View File

@ -60,8 +60,10 @@ from calibre.utils.resources import get_path as P
class DocViewer(Dialog):
def __init__(self, docs_dsl, parent=None):
def __init__(self, docs_dsl, builtins, function_type_string_method, parent=None):
self.docs_dsl = docs_dsl
self.builtins = builtins
self.function_type_string = function_type_string_method
super().__init__(title=_('Template function documentation'), name='template_editor_doc_viewer_dialog',
default_buttons=QDialogButtonBox.StandardButton.Close, parent=parent)
@ -69,7 +71,6 @@ class DocViewer(Dialog):
return QSize(800, 600)
def set_html(self, html):
print(html)
self.doc_viewer_widget.setHtml(html)
def setup_ui(self):
@ -84,18 +85,28 @@ class DocViewer(Dialog):
b.clicked.connect(self.show_all_functions)
b.setToolTip((_('Shows a list of all built-in functions in alphabetic order')))
def show_function(self):
self.set_html(
self.docs_dsl.document_to_html(self.all_functions[self.current_function_name].doc,
self.current_function_name))
def header_line(self, name):
return f'\n<h3>{name} ({self.function_type_string(name, longform=False)})</h3>\n'
def show_function(self, function_name):
if function_name not in self.builtins or not self.builtins[function_name].doc:
self.set_html(self.header_line(function_name) +
('No documentation provided'))
else:
self.set_html(self.header_line(function_name) +
self.docs_dsl.document_to_html(self.builtins[function_name].doc, function_name))
def show_all_functions(self):
funcs = formatter_functions().get_builtins()
result = []
a = result.append
for name in sorted(funcs):
a(f'\n<h2>{name}</h2>\n')
for name in sorted(self.builtins):
a(self.header_line(name))
try:
a(self.docs_dsl.document_to_html(funcs[name].doc.strip(), name))
doc = self.builtins[name].doc
if not doc:
a(_('No documentation provided'))
else:
a(self.docs_dsl.document_to_html(self.builtins[name].doc.strip(), name))
except Exception:
print('Exception in', name)
raise
@ -572,7 +583,8 @@ class TemplateDialog(QDialog, Ui_TemplateDialog):
def open_documentation_viewer(self):
if self.doc_viewer is None:
dv = self.doc_viewer = DocViewer(self.docs_dsl, self)
dv = self.doc_viewer = DocViewer(self.docs_dsl, self.all_functions,
self.function_type_string, parent=self)
dv.finished.connect(self.doc_viewer_finished)
dv.show()
if self.current_function_name is not None:
@ -1018,7 +1030,7 @@ def evaluate(book, context):
doc = self.all_functions[name].doc.strip()
self.documentation.setHtml(self.docs_dsl.document_to_html(doc, name))
if self.doc_viewer is not None:
self.doc_viewer_widget.setHtml(self.docs_dsl.document_to_html(self.all_functions[name].doc, name))
self.doc_viewer.show_function(name)
if name in self.builtins and name in self.builtin_source_dict:
self.source_code.setPlainText(self.builtin_source_dict[name])
else:

8
src/calibre/gui2/dialogs/template_dialog.ui
View File

@ -747,7 +747,9 @@ you the value as well as all the local variables&lt;/p&gt;</string>
<string>&amp;Documentation</string>
</property>
<property name="toolTip">
<string>Click this button to open the documentation in a separate dialog</string>
<string>Click this button to open the documentation in a separate dialog.
If no function is selected above then show all functions.
Selecting a function will show only that function's documentation</string>
</property>
</widget>
</item>
@ -762,8 +764,8 @@ you the value as well as all the local variables&lt;/p&gt;</string>
<property name="toolTip">
<string>&lt;p&gt;When using functions in a Single Function Mode template,
for example {title:uppercase()}, the first parameter 'value' is omitted. It is automatically replaced
by the value of the specified field.&lt;/p&gt; In all the other modes the value parameter
must be supplied.</string>
by the value of the specified field.&lt;/p&gt; &lt;p&gt;In all the other modes the value parameter
must be supplied.&lt;/p&gt;</string>
</property>
</widget>
</item>

27
src/calibre/utils/ffml_processor.py
View File

@ -43,7 +43,7 @@ class Node:
return self._text
def escaped_text(self):
return prepare_string_for_xml(self._text) #.replace('<', 'LESS_THAN') #.replace('>', '&gt;')
return prepare_string_for_xml(self._text)
class DocumentNode(Node):
@ -90,9 +90,15 @@ class UrlNode(Node):
def label(self):
return self._label
def escaped_label(self):
return prepare_string_for_xml(self._label)
def url(self):
return self._url
def escaped_url(self):
return prepare_string_for_xml(self._url)
class ListNode(Node):
@ -258,7 +264,7 @@ class FFMLProcessor:
elif tree.node_kind() == NodeKinds.BLANK_LINE:
result += '\n<br>\n<br>\n'
elif tree.node_kind() == NodeKinds.URL:
result += f'<a href="{tree.url()}">{tree.label()}</a>'
result += f'<a href="{tree.escaped_url()}">{tree.escaped_label()}</a>'
elif tree.node_kind() == NodeKinds.LIST:
result += '\n<ul>\n'
for child in tree.children():
@ -335,19 +341,28 @@ class FFMLProcessor:
result = self.tree_to_rst(child, indent, result)
return result
def document_to_rst(self, document, name):
def document_to_rst(self, document, name, indent=0, prefix=None):
"""
Given a document in the Formatter Function Markup Language (FFML), return
that document in RST (sphinx reStructuredText) format.
:param document: the text in FFML.
:param name: the name of the document, used during error
processing. It is usually the name of the function.
:param name: the name of the document, used during error
processing. It is usually the name of the function.
:param indent: the indenting level of the items in the tree. This is
usually zero, but can be greater than zero if you want
the RST output indented.
:param prefix: string. if supplied, this string replaces the indent
on the first line of the output. This permits specifying
an RST block, for example a bullet list
:return: a string containing the RST text
"""
return self.tree_to_rst(self.parse_document(document, name), 0)
doc = self.tree_to_rst(self.parse_document(document, name), indent)
if prefix is not None:
doc = prefix + doc.lstrip(' ')
return doc
# ============== Internal methods =================

252
src/calibre/utils/formatter_functions.py
View File

@ -219,7 +219,7 @@ class BuiltinStrcmp(BuiltinFormatterFunction):
arg_count = 5
category = 'Relational'
__doc__ = doc = _(
'''
r'''
``strcmp(x, y, lt, eq, gt)`` -- does a case-insensitive lexical comparison of
``x`` and ``y``. Returns ``lt`` if ``x < y``, ``eq`` if ``x == y``, otherwise
``gt``. This function can often be replaced by one of the lexical comparison
@ -240,7 +240,7 @@ class BuiltinStrcmpcase(BuiltinFormatterFunction):
arg_count = 5
category = 'Relational'
__doc__ = doc = _(
'''
r'''
``strcmpcase(x, y, lt, eq, gt)`` -- does a case-sensitive lexical comparison of
``x`` and ``y``. Returns ``lt`` if ``x < y``, ``eq`` if ``x == y``, otherwise
``gt``.
@ -265,7 +265,7 @@ class BuiltinCmp(BuiltinFormatterFunction):
category = 'Relational'
arg_count = 5
__doc__ = doc = _(
'''
r'''
``cmp(x, y, lt, eq, gt)`` -- compares ``x`` and ``y`` after converting both to
numbers. Returns ``lt`` if ``x <# y``, ``eq`` if ``x ==# y``, otherwise ``gt``.
This function can usually be replaced with one of the numeric compare operators
@ -287,7 +287,7 @@ class BuiltinFirstMatchingCmp(BuiltinFormatterFunction):
category = 'Relational'
arg_count = -1
__doc__ = doc = _(
'''
r'''
``first_matching_cmp(val, [ cmp, result, ]* else_result)`` -- compares ``val < cmp``
in sequence, returning the associated result for the first comparison that
succeeds. Returns else_result if no comparison succeeds.
@ -316,7 +316,7 @@ class BuiltinStrcat(BuiltinFormatterFunction):
arg_count = -1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``strcat(a [, b]*)`` -- can take any number of arguments. Returns a string
formed by concatenating all the arguments.
''')
@ -334,7 +334,7 @@ class BuiltinStrlen(BuiltinFormatterFunction):
arg_count = 1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``strlen(value)`` -- Returns the length of the string ``value``.
''')
@ -350,7 +350,7 @@ class BuiltinAdd(BuiltinFormatterFunction):
arg_count = -1
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``add(x [, y]*)`` -- returns the sum of its arguments. Throws an exception if an
argument is not a number. In most cases you can use the ``+`` operator instead
of this function.
@ -369,7 +369,7 @@ class BuiltinSubtract(BuiltinFormatterFunction):
arg_count = 2
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``subtract(x, y)`` -- returns ``x - y``. Throws an exception if either ``x`` or
``y`` are not numbers. This function can usually be replaced by the ``-``
operator.
@ -386,7 +386,7 @@ class BuiltinMultiply(BuiltinFormatterFunction):
arg_count = -1
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``multiply(x [, y]*)`` -- returns the product of its arguments. Throws an
exception if any argument is not a number. This function can usually be replaced
by the ``*`` operator.
@ -405,7 +405,7 @@ class BuiltinDivide(BuiltinFormatterFunction):
arg_count = 2
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``divide(x, y)`` -- returns ``x / y``. Throws an exception if either ``x`` or
``y`` are not numbers. This function can usually be replaced by the ``/``
operator.
@ -422,7 +422,7 @@ class BuiltinCeiling(BuiltinFormatterFunction):
arg_count = 1
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``ceiling(x)`` -- returns the smallest integer greater than or equal to ``x``.
Throws an exception if ``x`` is not a number.
''')
@ -437,7 +437,7 @@ class BuiltinFloor(BuiltinFormatterFunction):
arg_count = 1
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``floor(x)`` -- returns the largest integer less than or equal to ``x``. Throws
an exception if ``x`` is not a number.
''')
@ -452,7 +452,7 @@ class BuiltinRound(BuiltinFormatterFunction):
arg_count = 1
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``round(x)`` -- returns the nearest integer to ``x``. Throws an exception if
``x`` is not a number.
''')
@ -467,7 +467,7 @@ class BuiltinMod(BuiltinFormatterFunction):
arg_count = 2
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``mod(x, y)`` -- returns the ``floor`` of the remainder of ``x / y``. Throws an
exception if either ``x`` or ``y`` is not a number.
''')
@ -483,7 +483,7 @@ class BuiltinFractionalPart(BuiltinFormatterFunction):
arg_count = 1
category = 'Arithmetic'
__doc__ = doc = _(
'''
r'''
``fractional_part(value)`` -- returns the part of the value after the decimal
point. For example, ``fractional_part(3.14)`` returns ``0.14``. Throws an
exception if ``value`` is not a number.
@ -500,7 +500,7 @@ class BuiltinTemplate(BuiltinFormatterFunction):
category = 'Recursion'
__doc__ = doc = _(
'''
r'''
``template(x)`` -- evaluates ``x`` as a template. The evaluation is done in its
own context, meaning that variables are not shared between the caller and the
template evaluation. If not using General Program Mode, because the ``{`` and
@ -522,7 +522,7 @@ class BuiltinEval(BuiltinFormatterFunction):
arg_count = 1
category = 'Recursion'
__doc__ = doc = _(
'''
r'''
``eval(string)`` -- evaluates the string as a program, passing the local
variables. This permits using the template processor to construct complex
results from local variables. In
@ -546,7 +546,7 @@ class BuiltinAssign(BuiltinFormatterFunction):
arg_count = 2
category = 'Other'
__doc__ = doc = _(
'''
r'''
``assign(id, value)`` -- assigns ``value`` to ``id``, then returns ``value``. ``id``
must be an identifier, not an expression. In most cases you can use the ``=``
operator instead of this function.
@ -562,7 +562,7 @@ class BuiltinListSplit(BuiltinFormatterFunction):
arg_count = 3
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_split(list_val, sep, id_prefix)`` -- splits ``list_val`` into separate
values using ``sep``, then assigns the values to local variables named
``id_prefix_N`` where N is the position of the value in the list. The first item
@ -593,7 +593,7 @@ class BuiltinPrint(BuiltinFormatterFunction):
arg_count = -1
category = 'Other'
__doc__ = doc = _(
'''
r'''
``print(a [, b]*)`` -- prints the arguments to standard output. Unless you start
calibre from the command line (``calibre-debug -g``), the output will go into a
black hole. The ``print`` function always returns its first argument.
@ -609,7 +609,7 @@ class BuiltinField(BuiltinFormatterFunction):
arg_count = 1
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``field(lookup_name)`` -- returns the value of the metadata field with lookup name ``lookup_name``.
''')
@ -622,7 +622,7 @@ class BuiltinRawField(BuiltinFormatterFunction):
arg_count = -1
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``raw_field(lookup_name [, optional_default])`` -- returns the metadata field
named by ``lookup_name`` without applying any formatting. It evaluates and
returns the optional second argument ``optional_default`` if the field's value
@ -647,7 +647,7 @@ class BuiltinRawList(BuiltinFormatterFunction):
arg_count = 2
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``raw_list(lookup_name, separator)`` -- returns the metadata list named by
``lookup_name`` without applying any formatting or sorting, with the items
separated by separator.
@ -665,7 +665,7 @@ class BuiltinSubstr(BuiltinFormatterFunction):
arg_count = 3
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``substr(str, start, end)`` -- returns the ``start``'th through the ``end``'th
characters of ``str``. The first character in ``str`` is the zero'th character.
If ``end`` is negative then it indicates that many characters counting from the
@ -683,7 +683,7 @@ class BuiltinLookup(BuiltinFormatterFunction):
arg_count = -1
category = 'Iterating over values'
__doc__ = doc = _(
'''
r'''
``lookup(value, [ pattern, key, ]* else_key)`` -- The patterns will be checked against
the value in order. If a pattern matches then the value of the field named by
``key`` is returned. If no pattern matches then the value of the field named by
@ -712,7 +712,7 @@ class BuiltinTest(BuiltinFormatterFunction):
arg_count = 3
category = 'If-then-else'
__doc__ = doc = _(
'''
r'''
``test(value, text if not empty, text if empty)`` -- return ``text if not empty`` if
the value is not empty, otherwise return ``text if empty``.
''')
@ -729,7 +729,7 @@ class BuiltinContains(BuiltinFormatterFunction):
arg_count = 4
category = 'If-then-else'
__doc__ = doc = _(
'''
r'''
``contains(value, pattern, text if match, text if not match)`` -- checks if the value
is matched by the regular expression ``pattern``. Returns ``text if match`` if
the pattern matches the value, otherwise returns ``text if no match``.
@ -748,7 +748,7 @@ class BuiltinSwitch(BuiltinFormatterFunction):
arg_count = -1
category = 'Iterating over values'
__doc__ = doc = _(
'''
r'''
``switch(value, [pattern, value,]+ else_value)`` -- for each ``pattern, value`` pair,
checks if the value matches the regular expression ``pattern`` and if so returns
the associated ``value``. If no ``pattern`` matches, then ``else_value`` is
@ -773,7 +773,7 @@ class BuiltinSwitchIf(BuiltinFormatterFunction):
arg_count = -1
category = 'Iterating over values'
__doc__ = doc = _(
'''
r'''
``switch_if([test_expression, value_expression,]+ else_expression)`` -- for each
``test_expression, value_expression`` pair, checks if ``test_expression`` is
True (non-empty) and if so returns the result of ``value_expression``. If no
@ -800,7 +800,7 @@ class BuiltinStrcatMax(BuiltinFormatterFunction):
arg_count = -1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``strcat_max(max, string1 [, prefix2, string2]*)`` -- Returns a string formed by
concatenating the arguments. The returned value is initialized to ``string1``.
Strings made from ``prefix, string`` pairs are added to the end of the value as
@ -837,7 +837,7 @@ class BuiltinInList(BuiltinFormatterFunction):
arg_count = -1
category = 'List lookup'
__doc__ = doc = _(
'''
r'''
``list_contains(value, separator, [ pattern, found_val, ]* not_found_val)`` -- interpret the
value as a list of items separated by ``separator``, checking the ``pattern``
against each item in the list. If the ``pattern`` matches an item then return
@ -873,7 +873,7 @@ class BuiltinStrInList(BuiltinFormatterFunction):
arg_count = -1
category = 'List lookup'
__doc__ = doc = _(
'''
r'''
``str_in_list(value, separator, [ string, found_val, ]+ not_found_val)`` -- interpret
the value as a list of items separated by ``separator`` then compare ``string``
against each value in the list. The ``string`` is not a regular expression. If
@ -951,7 +951,7 @@ class BuiltinRe(BuiltinFormatterFunction):
arg_count = 3
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``re(value, pattern, replacement)`` -- return the value after applying the regular
expression. All instances of ``pattern`` in the value are replaced with
``replacement``. The template language uses case insensitive
@ -968,7 +968,7 @@ class BuiltinReGroup(BuiltinFormatterFunction):
arg_count = -1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``re_group(value, pattern [, template_for_group]*)`` -- return a string made by
applying the regular expression pattern to ``value`` and replacing each matched
instance with the value returned by the corresponding template. In
@ -977,7 +977,7 @@ instance with the value returned by the corresponding template. In
The following example looks for a series with more than one word and uppercases the first word:
[CODE]
program: re_group(field('series'), "(\\S* )(.*)", "{$:uppercase()}", "{$}")'}
program: re_group(field('series'), "(\S* )(.*)", "{$:uppercase()}", "{$}")'}
[/CODE]
''')
@ -1006,7 +1006,7 @@ class BuiltinSwapAroundComma(BuiltinFormatterFunction):
arg_count = 1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``swap_around_comma(value)`` -- given a value of the form ``B, A``, return ``A B``.
This is most useful for converting names in LN, FN format to FN LN. If there is
no comma in the value then the function returns the value unchanged.
@ -1021,7 +1021,7 @@ class BuiltinIfempty(BuiltinFormatterFunction):
arg_count = 2
category = 'If-then-else'
__doc__ = doc = _(
'''
r'''
``ifempty(value, text if empty)`` -- if the value is not empty then return that value,
otherwise return ``text if empty``.
''')
@ -1038,7 +1038,7 @@ class BuiltinShorten(BuiltinFormatterFunction):
arg_count = 4
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``shorten(value, left chars, middle text, right chars)`` -- Return a shortened version
of the value, consisting of ``left chars`` characters from the beginning of the
value, followed by ``middle text``, followed by ``right chars`` characters from
@ -1072,7 +1072,7 @@ class BuiltinCount(BuiltinFormatterFunction):
aliases = ['count']
__doc__ = doc = _(
'''
r'''
``list_count(value, separator)`` -- interprets the value as a list of items separated by
``separator`` and returns the number of items in the list. Most lists use
a comma as the separator, but ``authors`` uses an ampersand (&).
@ -1093,7 +1093,7 @@ class BuiltinListCountMatching(BuiltinFormatterFunction):
aliases = ['count_matching']
__doc__ = doc = _(
'''
r'''
``list_count_matching(list, pattern, separator)`` -- interprets ``list`` as a
list of items separated by ``separator``, returning the number of items in the
list that match the regular expression ``pattern``.
@ -1114,7 +1114,7 @@ class BuiltinListitem(BuiltinFormatterFunction):
arg_count = 3
category = 'List lookup'
__doc__ = doc = _(
'''
r'''
``list_item(value, index, separator)`` -- interpret the value as a list of items
separated by ``separator``, returning the 'index'th item. The first item is
number zero. The last item has the index ``-1`` as in
@ -1139,7 +1139,7 @@ class BuiltinSelect(BuiltinFormatterFunction):
arg_count = 2
category = 'List lookup'
__doc__ = doc = _(
'''
r'''
``select(value, key)`` -- interpret the value as a comma-separated list of items with
each item having the form ``id:value`` (the calibre ``identifier`` format). The
function finds the first pair with the id equal to key and returns the
@ -1163,7 +1163,7 @@ class BuiltinApproximateFormats(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``approximate_formats()`` -- return a comma-separated list of formats associated
with the book. Because the list comes from calibre's database instead of the
file system, there is no guarantee that the list is correct, although it
@ -1171,8 +1171,8 @@ probably is. Note that resulting format names are always uppercase, as in EPUB.
The ``approximate_formats()`` function is much faster than the ``formats_...``
functions.
This function works only in the GUI. If you want to use these values in save-to-
disk or send-to-device templates then you must make a custom "Column built from
This function works only in the GUI. If you want to use these values in save-to-disk
or send-to-device templates then you must make a custom "Column built from
other columns", use the function in that column's template, and use that
column's value in your save/send templates.
''')
@ -1192,7 +1192,7 @@ class BuiltinFormatsModtimes(BuiltinFormatterFunction):
arg_count = 1
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``formats_modtimes(date_format_string)`` -- return a comma-separated list of
colon-separated items ``FMT:DATE`` representing modification times for the
formats of a book. The ``date_format_string`` parameter specifies how the date
@ -1217,7 +1217,7 @@ class BuiltinFormatsSizes(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``formats_sizes()`` -- return a comma-separated list of colon-separated
``FMT:SIZE`` items giving the sizes of the formats of a book in bytes. You can
use the ``select()`` function to get the size for a specific format. Note that
@ -1237,7 +1237,7 @@ class BuiltinFormatsPaths(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``formats_paths()`` -- return a comma-separated list of colon-separated items
``FMT:PATH`` giving the full path to the formats of a book. You can use the
``select()`` function to get the path for a specific format. Note that format names
@ -1257,7 +1257,7 @@ class BuiltinHumanReadable(BuiltinFormatterFunction):
arg_count = 1
category = 'Formatting values'
__doc__ = doc = _(
'''
r'''
``human_readable(value)`` -- expects the value to be a number and returns a string
representing that number in KB, MB, GB, etc.
''')
@ -1274,7 +1274,7 @@ class BuiltinFormatNumber(BuiltinFormatterFunction):
arg_count = 2
category = 'Formatting values'
__doc__ = doc = _(
'''
r'''
``format_number(value, template)`` -- interprets the value as a number and formats that
number using a Python formatting template such as ``{0:5.2f}`` or ``{0:,d}`` or
``${0:5,.2f}``. The formatting template must begin with ``{0:`` and end with
@ -1312,7 +1312,7 @@ class BuiltinSublist(BuiltinFormatterFunction):
arg_count = 4
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``sublist(value, start_index, end_index, separator)`` -- interpret the value as a
list of items separated by ``separator``, returning a new list made from the
items from ``start_index`` to ``end_index``. The first item is number zero. If
@ -1321,9 +1321,9 @@ case, an end_index of zero is assumed to be the length of the list.
Examples assuming that the tags column (which is comma-separated) contains "A, B ,C":
[LIST]
[*]``{tags:sublist(0,1,\\,)}`` returns "A"
[*]``{tags:sublist(-1,0,\\,)}`` returns "C"
[*]``{tags:sublist(0,-1,\\,)}`` returns "A, B"
[*]``{tags:sublist(0,1,\,)}`` returns "A"
[*]``{tags:sublist(-1,0,\,)}`` returns "C"
[*]``{tags:sublist(0,-1,\,)}`` returns "A, B"
[/LIST]
''')
@ -1351,9 +1351,9 @@ class BuiltinSubitems(BuiltinFormatterFunction):
arg_count = 3
category = 'List manipulation'
__doc__ = doc = _(
'''
``subitems(value, start_index, end_index)`` -- This function breaks apart lists of tag-
like hierarchical items such as genres. It interprets the value as a comma-
r'''
``subitems(value, start_index, end_index)`` -- This function breaks apart lists of
tag-like hierarchical items such as genres. It interprets the value as a comma-
separated list of tag-like items, where each item is a period-separated list. It
returns a new list made by extracting from each item the components from
``start_index`` to ``end_index``, then merging the results back together.
@ -1409,7 +1409,7 @@ class BuiltinFormatDate(BuiltinFormatterFunction):
arg_count = 2
category = 'Formatting values'
__doc__ = doc = _(
'''
r'''
``format_date(value, format_string)`` -- format the value, which must be a date
string, using the format_string, returning a string. It is best if the date is
in ISO format as using other date formats often causes errors because the actual
@ -1473,7 +1473,7 @@ class BuiltinFormatDateField(BuiltinFormatterFunction):
arg_count = 2
category = 'Formatting values'
__doc__ = doc = _(
'''
r'''
``format_date_field(field_name, format_string)`` -- format the value in the
field ``field_name``, which must be the lookup name of a date field, either
standard or custom. See ``format_date()`` for the formatting codes. This
@ -1519,7 +1519,7 @@ class BuiltinUppercase(BuiltinFormatterFunction):
arg_count = 1
category = 'String case changes'
__doc__ = doc = _(
'''
r'''
``uppercase(value)`` -- returns the value in upper case.
''')
@ -1532,7 +1532,7 @@ class BuiltinLowercase(BuiltinFormatterFunction):
arg_count = 1
category = 'String case changes'
__doc__ = doc = _(
'''
r'''
``lowercase(value)`` -- returns the value in lower case.
''')
@ -1545,7 +1545,7 @@ class BuiltinTitlecase(BuiltinFormatterFunction):
arg_count = 1
category = 'String case changes'
__doc__ = doc = _(
'''
r'''
``titlecase(value)`` -- returns the value in title case.
''')
@ -1558,7 +1558,7 @@ class BuiltinCapitalize(BuiltinFormatterFunction):
arg_count = 1
category = 'String case changes'
__doc__ = doc = _(
'''
r'''
``capitalize(value)`` -- returns the value with the first letter in upper case and the rest lower case.
''')
@ -1571,7 +1571,7 @@ class BuiltinBooksize(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``booksize()`` -- returns the value of the calibre ``size`` field. Returns '' if the book has no formats.
This function works only in the GUI. If you want to use this value in save-to-disk
@ -1598,7 +1598,7 @@ class BuiltinOndevice(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``ondevice()`` -- return the string ``'Yes'`` if ``ondevice`` is set, otherwise
return the empty string. This function works only in the GUI. If you want to use
this value in save-to-disk or send-to-device templates then you must make a
@ -1619,7 +1619,7 @@ class BuiltinAnnotationCount(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``annotation_count()`` -- return the total number of annotations of all types
attached to the current book. This function works only in the GUI.
''')
@ -1634,10 +1634,10 @@ class BuiltinIsMarked(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``is_marked()`` -- check whether the book is `marked` in calibre. If it is then
return the value of the mark, either ``'true'`` (lower case) or a comma-
separated list of named marks. Returns ``''`` (the empty string) if the book is
return the value of the mark, either ``'true'`` (lower case) or a comma-separated
list of named marks. Returns ``''`` (the empty string) if the book is
not marked. This function works only in the GUI.
''')
@ -1651,7 +1651,7 @@ class BuiltinSeriesSort(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``series_sort()`` -- returns the series sort value.
''')
@ -1668,7 +1668,7 @@ class BuiltinHasCover(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``has_cover()`` -- return ``'Yes'`` if the book has a cover, otherwise the empty string.
''')
@ -1683,7 +1683,7 @@ class BuiltinFirstNonEmpty(BuiltinFormatterFunction):
arg_count = -1
category = 'Iterating over values'
__doc__ = doc = _(
'''
r'''
``first_non_empty(value [, value]*)`` -- returns the first ``value`` that is not
empty. If all values are empty, then the empty string is returned. You can have
as many values as you want.
@ -1703,7 +1703,7 @@ class BuiltinAnd(BuiltinFormatterFunction):
arg_count = -1
category = 'Boolean'
__doc__ = doc = _(
'''
r'''
``and(value [, value]*)`` -- returns the string "1" if all values are not empty,
otherwise returns the empty string. You can have as many values as you want. In
most cases you can use the ``&&`` operator instead of this function. One reason
@ -1726,7 +1726,7 @@ class BuiltinOr(BuiltinFormatterFunction):
arg_count = -1
category = 'Boolean'
__doc__ = doc = _(
'''
r'''
``or(value [, value]*)`` -- returns the string ``'1'`` if any value is not
empty, otherwise returns the empty string. You can have as many values as you
want. This function can usually be replaced by the ``||`` operator. A reason it
@ -1748,7 +1748,7 @@ class BuiltinNot(BuiltinFormatterFunction):
arg_count = 1
category = 'Boolean'
__doc__ = doc = _(
'''
r'''
``not(value)`` -- returns the string "1" if the value is empty, otherwise
returns the empty string. This function can usually be replaced with the unary
not (``!``) operator.
@ -1763,14 +1763,14 @@ class BuiltinListJoin(BuiltinFormatterFunction):
arg_count = -1
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_join(with_separator, list1, separator1 [, list2, separator2]*)`` --
return a list made by joining the items in the source lists (``list1`` etc)
using ``with_separator`` between the items in the result list. Items in each
source ``list[123...]`` are separated by the associated ``separator[123...]``. A
list can contain zero values. It can be a field like ``publisher`` that is
single-valued, effectively a one-item list. Duplicates are removed using a case-
insensitive comparison. Items are returned in the order they appear in the
single-valued, effectively a one-item list. Duplicates are removed using a
case-insensitive comparison. Items are returned in the order they appear in the
source lists. If items on lists differ only in letter case then the last is
used. All separators can be more than one character.
@ -1816,10 +1816,10 @@ class BuiltinListUnion(BuiltinFormatterFunction):
arg_count = 3
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_union(list1, list2, separator)`` -- return a list made by merging the
items in ``list1`` and ``list2``, removing duplicate items using a case-
insensitive comparison. If items differ in case, the one in ``list1`` is used.
items in ``list1`` and ``list2``, removing duplicate items using a case-insensitive
comparison. If items differ in case, the one in ``list1`` is used.
The items in ``list1`` and ``list2`` are separated by ``separator``, as are the
items in the returned list. Aliases: ``merge_lists()``, ``list_union()``
''')
@ -1838,7 +1838,7 @@ class BuiltinRange(BuiltinFormatterFunction):
arg_count = -1
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``range(start, stop, step, limit)`` -- returns a list of numbers generated by
looping over the range specified by the parameters start, stop, and step, with a
maximum length of limit. The first value produced is 'start'. Subsequent values
@ -1891,7 +1891,7 @@ class BuiltinListRemoveDuplicates(BuiltinFormatterFunction):
arg_count = 2
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_remove_duplicates(list, separator)`` -- return a list made by removing
duplicate items in ``list``. If items differ only in case then the last is
returned. The items in ``list`` are separated by ``separator``, as are the items
@ -1910,7 +1910,7 @@ class BuiltinListDifference(BuiltinFormatterFunction):
arg_count = 3
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_difference(list1, list2, separator)`` -- return a list made by removing
from ``list1`` any item found in ``list2`` using a case-insensitive comparison.
The items in ``list1`` and ``list2`` are separated by separator, as are the
@ -1935,7 +1935,7 @@ class BuiltinListIntersection(BuiltinFormatterFunction):
arg_count = 3
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_intersection(list1, list2, separator)`` -- return a list made by removing
from ``list1`` any item not found in ``list2``, using a case-insensitive
comparison. The items in ``list1`` and ``list2`` are separated by separator, as
@ -1960,7 +1960,7 @@ class BuiltinListSort(BuiltinFormatterFunction):
arg_count = 3
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_sort(list, direction, separator)`` -- return ``list`` sorted using a
case-insensitive lexical sort. If ``direction`` is zero (number or character),
``list`` is sorted ascending, otherwise descending. The list items are separated
@ -1979,7 +1979,7 @@ class BuiltinListEquals(BuiltinFormatterFunction):
arg_count = 6
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_equals(list1, sep1, list2, sep2, yes_val, no_val)`` -- return ``yes_val``
if ``list1`` and ``list2`` contain the same items, otherwise return ``no_val``.
The items are determined by splitting each list using the appropriate separator
@ -2000,7 +2000,7 @@ class BuiltinListRe(BuiltinFormatterFunction):
arg_count = 4
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_re(src_list, separator, include_re, opt_replace)`` -- Construct a list by
first separating ``src_list`` into items using the ``separator`` character. For
each item in the list, check if it matches ``include_re``. If it does then add
@ -2028,7 +2028,7 @@ class BuiltinListReGroup(BuiltinFormatterFunction):
arg_count = -1
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_re_group(src_list, separator, include_re, search_re [,template_for_group]*)``
-- Like list_re except replacements are not optional. It
uses ``re_group(item, search_re, template ...)`` when doing the replacements.
@ -2070,7 +2070,7 @@ class BuiltinToday(BuiltinFormatterFunction):
arg_count = 0
category = 'Date functions'
__doc__ = doc = _(
'''
r'''
``today()`` -- return a date+time string for today (now). This value is designed
for use in ``format_date`` or ``days_between``, but can be manipulated like any
other string. The date is in [URL href="https://en.wikipedia.org/wiki/ISO_8601"]ISO[/URL]
@ -2086,7 +2086,7 @@ class BuiltinDaysBetween(BuiltinFormatterFunction):
arg_count = 2
category = 'Date functions'
__doc__ = doc = _(
'''
r'''
``days_between(date1, date2)`` -- return the number of days between ``date1``
and ``date2``. The number is positive if ``date1`` is greater than ``date2``,
otherwise negative. If either ``date1`` or ``date2`` are not dates, the function
@ -2112,7 +2112,7 @@ class BuiltinDateArithmetic(BuiltinFormatterFunction):
arg_count = -1
category = 'Date functions'
__doc__ = doc = _(
'''
r'''
``date_arithmetic(date, calc_spec, fmt)`` -- Calculate a new date from ``date``
using ``calc_spec``. Return the new date formatted according to optional
``fmt``: if not supplied then the result will be in ISO format. The calc_spec is
@ -2191,7 +2191,7 @@ class BuiltinLanguageCodes(BuiltinFormatterFunction):
arg_count = 1
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``language_codes(lang_strings)`` -- return the
[URL href="https://www.loc.gov/standards/iso639-2/php/code_list.php"]language codes[/URL] for the language
names passed in ``lang_strings``. The strings must be in the language of the
@ -2215,7 +2215,7 @@ class BuiltinCurrentLibraryName(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``current_library_name()`` -- return the last name on the path to the current calibre library.
''')
@ -2229,7 +2229,7 @@ class BuiltinCurrentLibraryPath(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``current_library_path()`` -- return the full path to the current calibre
library.
''')
@ -2244,7 +2244,7 @@ class BuiltinFinishFormatting(BuiltinFormatterFunction):
arg_count = 4
category = 'Formatting values'
__doc__ = doc = _(
'''
r'''
``finish_formatting(val, format, prefix, suffix)`` -- apply the ``format``, ``prefix``, and
``suffix`` to a value in the same way as done in a template like
``{series_index:05.2f| - |- }``. This function is provided to ease conversion of
@ -2256,13 +2256,13 @@ program: finish_formatting(field("series_index"), "05.2f", " - ", " - ")
[/CODE]
Another example: for the template:
[CODE]
{series:re(([^\\s])[^\\s]+(\\s|$),\\1)}{series_index:0>2s| - | - }{title}
{series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title}
[/CODE]
use:
[CODE]
program:
strcat(
re(field('series'), '([^\\s])[^\\s]+(\\s|$)', '\\1'),
re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
field('title')
)
@ -2280,7 +2280,7 @@ class BuiltinVirtualLibraries(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``virtual_libraries()`` -- return a comma-separated list of Virtual libraries that
contain this book. This function works only in the GUI. If you want to use these
values in save-to-disk or send-to-device templates then you must make a custom
@ -2302,7 +2302,7 @@ class BuiltinCurrentVirtualLibraryName(BuiltinFormatterFunction):
arg_count = 0
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``current_virtual_library_name()`` -- return the name of the current
virtual library if there is one, otherwise the empty string. Library name case
is preserved. Example:
@ -2341,7 +2341,7 @@ class BuiltinTransliterate(BuiltinFormatterFunction):
arg_count = 1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``transliterate(value)`` -- Return a string in a latin alphabet formed by
approximating the sound of the words in the source field. For example, if the
source field is ``Фёдор Миха́йлович Достоевский`` this function returns ``Fiodor
@ -2358,7 +2358,7 @@ class BuiltinGetLink(BuiltinFormatterFunction):
arg_count = 2
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``get_link(field_name, field_value)`` -- fetch the link for field ``field_name``
with value ``field_value``. If there is no attached link, return the empty
string. Examples:
@ -2401,7 +2401,7 @@ class BuiltinAuthorLinks(BuiltinFormatterFunction):
arg_count = 2
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``author_links(val_separator, pair_separator)`` -- returns a string containing a
list of authors and those authors' link values in the form:
``author1 val_separator author1_link pair_separator author2 val_separator author2_link`` etc.
@ -2432,7 +2432,7 @@ class BuiltinAuthorSorts(BuiltinFormatterFunction):
arg_count = 1
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``author_sorts(val_separator)`` -- returns a string containing a list of
author's sort values for the authors of the book. The sort is the one in the
author metadata information, which can be different from the author_sort in books. The
@ -2455,7 +2455,7 @@ class BuiltinConnectedDeviceName(BuiltinFormatterFunction):
arg_count = 1
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``connected_device_name(storage_location_key)`` -- if a device is connected then
return the device name, otherwise return the empty string. Each storage location
on a device has its own device name. The ``storage_location_key`` names are
@ -2493,7 +2493,7 @@ class BuiltinConnectedDeviceUUID(BuiltinFormatterFunction):
arg_count = 1
category = 'Get values from metadata'
__doc__ = doc = _(
'''
r'''
``connected_device_uuid(storage_location_key)`` -- if a device is connected then
return the device uuid (unique id), otherwise return the empty string. Each
storage location on a device has a different uuid. The ``storage_location_key``
@ -2531,7 +2531,7 @@ class BuiltinCheckYesNo(BuiltinFormatterFunction):
arg_count = 4
category = 'If-then-else'
__doc__ = doc = _(
'''
r'''
``check_yes_no(field_name, is_undefined, is_false, is_true)`` -- checks if the
value of the yes/no field named by the lookup name ``field_name`` is one of the
values specified by the parameters, returning ``'yes'`` if a match is found
@ -2568,7 +2568,7 @@ class BuiltinRatingToStars(BuiltinFormatterFunction):
arg_count = 2
category = 'Formatting values'
__doc__ = doc = _(
'''
r'''
``rating_to_stars(value, use_half_stars)`` -- Returns the value as string of star
(``★``) characters. The value must be a number between 0 and 5. Set
use_half_stars to 1 if you want half star characters for fractional numbers
@ -2594,7 +2594,7 @@ class BuiltinSwapAroundArticles(BuiltinFormatterFunction):
arg_count = 2
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``swap_around_articles(value, separator)`` -- returns the value with articles moved to
the end. The value can be a list, in which case each item in the list is
processed. If the value is a list then you must provide the ``separator``. If no
@ -2621,7 +2621,7 @@ class BuiltinArguments(BuiltinFormatterFunction):
arg_count = -1
category = 'Other'
__doc__ = doc = _(
'''
r'''
``arguments(id[=expression] [, id[=expression]]*)`` -- Used in a stored
template to retrieve the arguments passed in the call. It both declares and
initializes local variables with the supplied names, the ``id``s, making them
@ -2642,7 +2642,7 @@ class BuiltinGlobals(BuiltinFormatterFunction):
arg_count = -1
category = 'Other'
__doc__ = doc = _(
'''
r'''
``globals(id[=expression] [, id[=expression]]*)`` -- Retrieves "global variables"
that can be passed into the formatter. The name ``id`` is the name of the global
variable. It both declares and initializes local variables with the names of the
@ -2677,7 +2677,7 @@ class BuiltinFieldExists(BuiltinFormatterFunction):
arg_count = 1
category = 'If-then-else'
__doc__ = doc = _(
'''
r'''
``field_exists(lookup_name)`` -- checks if a field (column) with the lookup name
``lookup_name`` exists, returning ``'1'`` if so and the empty string if not.
''')
@ -2693,9 +2693,9 @@ class BuiltinCharacter(BuiltinFormatterFunction):
arg_count = 1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``character(character_name)`` -- returns the character named by character_name.
For example, ``character('newline')`` returns a newline character (``'\\n'``).
For example, ``character('newline')`` returns a newline character (``'\n'``).
The supported character names are ``newline``, ``return``, ``tab``, and
``backslash``. This function is used to put these characters into the output
of templates.
@ -2711,7 +2711,7 @@ class BuiltinToHex(BuiltinFormatterFunction):
arg_count = 1
category = 'String manipulation'
__doc__ = doc = _(
'''
r'''
``to_hex(val)`` -- returns the string ``val`` encoded in hex. This is useful
when constructing calibre URLs.
''')
@ -2725,7 +2725,7 @@ class BuiltinUrlsFromIdentifiers(BuiltinFormatterFunction):
arg_count = 2
category = 'Formatting values'
__doc__ = doc = _(
'''
r'''
``urls_from_identifiers(identifiers, sort_results)`` -- given a comma-separated
list of ``identifiers``, where an ``identifier`` is a colon-separated pair of
values (``id_name:id_value``), returns a comma-separated list of HTML URLs
@ -2762,7 +2762,7 @@ class BuiltinBookCount(BuiltinFormatterFunction):
arg_count = 2
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``book_count(query, use_vl)`` -- returns the count of books found by searching
for ``query``. If ``use_vl`` is ``0`` (zero) then virtual libraries are ignored.
This function and its companion ``book_values()`` are particularly useful in
@ -2821,7 +2821,7 @@ class BuiltinBookValues(BuiltinFormatterFunction):
arg_count = 4
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``book_values(column, query, sep, use_vl)`` -- returns a list of the unique
values contained in the column ``column`` (a lookup name), separated by ``sep``,
in the books found by searching for ``query``. If ``use_vl`` is ``0`` (zero)
@ -2860,7 +2860,7 @@ class BuiltinHasExtraFiles(BuiltinFormatterFunction):
arg_count = -1
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``has_extra_files([pattern])`` -- returns the count of extra files, otherwise ''
(the empty string). If the optional parameter ``pattern`` (a regular expression)
is supplied then the list is filtered to files that match ``pattern`` before the
@ -2891,7 +2891,7 @@ class BuiltinExtraFileNames(BuiltinFormatterFunction):
arg_count = -1
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``extra_file_names(sep [, pattern])`` -- returns a ``sep``-separated list of
extra files in the book's ``data/`` folder. If the optional parameter
``pattern``, a regular expression, is supplied then the list is filtered to
@ -2922,7 +2922,7 @@ class BuiltinExtraFileSize(BuiltinFormatterFunction):
arg_count = 1
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``extra_file_size(file_name)`` -- returns the size in bytes of the extra file
``file_name`` in the book's ``data/`` folder if it exists, otherwise ``-1``. See
also the functions ``has_extra_files()``, ``extra_file_names()`` and
@ -2947,7 +2947,7 @@ class BuiltinExtraFileModtime(BuiltinFormatterFunction):
arg_count = 2
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``extra_file_modtime(file_name, format_string)`` -- returns the modification
time of the extra file ``file_name`` in the book's ``data/`` folder if it
exists, otherwise ``-1``. The modtime is formatted according to
@ -2979,7 +2979,7 @@ class BuiltinGetNote(BuiltinFormatterFunction):
arg_count = 3
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``get_note(field_name, field_value, plain_text)`` -- fetch the note for field
'field_name' with value 'field_value'. If ``plain_text`` is empty, return the
note's HTML including images. If ``plain_text`` is ``1`` (or ``'1'``), return the
@ -3041,7 +3041,7 @@ class BuiltinHasNote(BuiltinFormatterFunction):
arg_count = 2
category = 'Template database functions'
__doc__ = doc = _(
'''
r'''
``has_note(field_name, field_value)``. This function has two variants:
[LIST]
[*]if ``field_value`` is not ``''`` (the empty string) return ``'1'`` if the
@ -3092,7 +3092,7 @@ class BuiltinIsDarkMode(BuiltinFormatterFunction):
arg_count = 0
category = 'other'
__doc__ = doc = _(
'''
r'''
``is_dark_mode()`` -- returns ``'1'`` if calibre is running in dark mode, ``''``
(the empty string) otherwise. This function can be used in advanced color and
icon rules to choose different colors/icons according to the mode. Example:
@ -3115,7 +3115,7 @@ class BuiltinFieldListCount(BuiltinFormatterFunction):
arg_count = 0
category = 'List manipulation'
__doc__ = doc = _(
'''
r'''
``list_count_field(lookup_name)``-- returns the count of items in the field with
the lookup name ``lookup_name``. The field must be multi-valued such as
``authors`` or ``tags``, otherwise the function raises an error. This function