From a5c99c74966ac5c75835755a5d873f219abf3caa Mon Sep 17 00:00:00 2001 From: Charles Haley Date: Thu, 14 Nov 2024 16:45:07 +0000 Subject: [PATCH] 1) Change to an r-string to make it easier to edit and test in external programs. Doubled backslashes are a bother when doing copy/paste. 2) Updates and corrections to the information text. --- .../gui2/dialogs/template_general_info.py | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/src/calibre/gui2/dialogs/template_general_info.py b/src/calibre/gui2/dialogs/template_general_info.py index 47877fb966..a50c8284df 100644 --- a/src/calibre/gui2/dialogs/template_general_info.py +++ b/src/calibre/gui2/dialogs/template_general_info.py @@ -32,15 +32,20 @@ class GeneralInformationDialog(Dialog): e.setHtml(FFMLProcessor().document_to_html(information, 'Template Information')) -information = ''' +information = r''' [LIST] [*]`Functions in Single Function Mode templates` - -When using functions in a Single function mode template, +[LIST] +[*]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. In all the other modes the value parameter must be supplied. +[*]Do not use subtemplates "(`{...}`)" as function arguments because they will often not work. +Instead, use Template Program Mode and General Program Mode. +[*]Do not use subtemplates "(`{...}`)" or functions (see below) in the prefix or the suffix +for the same reason as above; they will often not work. +[/LIST] [*]`Editor for asssting with template function documentation` An editor is available for helping write template function documentation. Given a document @@ -62,28 +67,29 @@ document formatter functions. It is based on a combination of RST used by sphinx and BBCODE used by many bulletin board systems such as MobileRead. It provides a way to specify: [LIST] -[*]Inline program code text: surround this text with \\`\\` as in \\`\\`foo\\`\\`. Tags inside the text are ignored. -[*]Italic text: surround this text with \\`. Example \\`foo\\` produces `foo`. +[*]Inline program code text: surround this text with \`\` as in \`\`foo\`\`. Tags inside the text are ignored. +[*]Italic text: surround this text with \`. Example: \`foo\` produces `foo`. +[*]Bold text: surround this text with \[B]text\[\B] tags. Example: \[B]foo\[/B] produces [B]foo[/B]. [*]Text intended to reference a calibre GUI action. This uses RST syntax.\ - Example: \\:guilabel\\:\\`Preferences->Advanced->Template functions\\`. For HTML the produced text is in a different font, as in: :guilabel:`Some text` -[*]Empty lines, indicated by two newlines in a row. A visible empty line in the FFMC will become an empty line in the output. + Example: \:guilabel\:\`Preferences->Advanced->Template functions\`. For HTML the produced text is in a different font, as in: :guilabel:`Some text` +[*]Empty lines, indicated by two newlines in a row. A visible empty line in the FFML +will become an empty line in the output. [*]URLs. The syntax is similar to BBCODE: ``[URL href="http..."]Link text[/URL]``.\ Example: ``[URL href="https://en.wikipedia.org/wiki/ISO_8601"]ISO[/URL]`` produces [URL href="https://en.wikipedia.org/wiki/ISO_8601"]ISO[/URL] [*]Internal function reference links. These are links to formatter function -documentation. The syntax is the same as guilabel. Example: ``:ref:`get_note` ``. +documentation. The syntax is the same as guilabel. Example: ``:ref:\`get_note\```. The characters '()' are automatically added to the function name when displayed. For HTML it generates the same as the inline program code text -operator (\\`\\`) with no link. Example: ``:ref:`add` `` produces ``add()``. +operator (\`\`) with no link. Example: ``:ref:`add` `` produces ``add()``. For RST it generates a ``:ref:`` reference that works only in an RST document -containing formatter function documentation. Example: ``:ref:`get_note` `` -generates \\:ref\\:\\`get_note() \\` +containing formatter function documentation. Example: ``:ref:\`get_note\``` +generates \:ref\:\`get_note() \` [*]Example program code text blocks. Surround the code block with ``[CODE]`` and ``[/CODE]`` tags. These tags must be first on a line. Example: - [CODE] -\\[CODE]program: +\[CODE]program: get_note('authors', 'Isaac Asimov', 1) -\\[/CODE] +\[/CODE] [/CODE] produces [CODE] @@ -97,18 +103,18 @@ elements. Example: a two bullet list containing CODE blocks [CODE] -\\[LIST] +\[LIST] [*]Return the HTML of the note attached to the tag `Fiction`: -\\[CODE] +\[CODE] program: get_note('tags', 'Fiction', '') -\\[/CODE] +\[/CODE] [*]Return the plain text of the note attached to the author `Isaac Asimov`: -\\[CODE] +\[CODE] program: get_note('authors', 'Isaac Asimov', 1) -\\[/CODE] -\\[/LIST] +\[/CODE] +\[/LIST] [/CODE] [*]HTML output contains no CSS and does not start with a tag such as
or

.