From ab9ba6a3afe2e1c94638db3975ae5d2883afd101 Mon Sep 17 00:00:00 2001 From: Charles Haley Date: Tue, 22 Jul 2025 12:26:07 +0100 Subject: [PATCH] Move the FFML general documentation to formatter_functions() so it can be processed before sending it to transifex. --- .../gui2/dialogs/template_general_info.py | 107 +---------------- src/calibre/utils/formatter_functions.py | 108 ++++++++++++++++++ 2 files changed, 109 insertions(+), 106 deletions(-) diff --git a/src/calibre/gui2/dialogs/template_general_info.py b/src/calibre/gui2/dialogs/template_general_info.py index f82246bef5..58303898e6 100644 --- a/src/calibre/gui2/dialogs/template_general_info.py +++ b/src/calibre/gui2/dialogs/template_general_info.py @@ -14,6 +14,7 @@ from qt.core import QDialogButtonBox, QVBoxLayout from calibre.constants import iswindows from calibre.gui2.widgets2 import Dialog, HTMLDisplay from calibre.utils.ffml_processor import FFMLProcessor +from calibre.utils.formatter_functions import general_doc, ffml_doc class GeneralInformationDialog(Dialog): @@ -41,112 +42,6 @@ class GeneralInformationDialog(Dialog): e.setHtml(html) -general_doc = r''' -[LIST] -[*]`Functions in Single Function Mode templates` -[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 assisting with template function documentation` - -An editor is available for helping write template function documentation. Given a document -in the Formatter Function Markup Language, it show the resulting HTML. The HTML is updated as you edit. - -This editor is available in two ways: -[LIST] -[*]Using the command -[CODE] -calibre-debug -c "from calibre.gui2.dialogs.ff_doc_editor import main; main()"[/CODE] -all on one line. -[*]By defining a keyboard shortcut in calibre for the action `Open the template -documentation editor` in the `Miscellaneous` section. There is no default shortcut. -[/LIST] -[/LIST] -''' - -ffml_doc = r''' -Format Function Markup Language (FFML) is a basic markup language used to -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] -[*][B]Inline program code text[/B]: surround this text with \`\` as in \`\`foo\`\`. -Tags inside the text are ignored. if the code text ends with a `\'` character, put -a space before the closing \`\` characters. Trailing blanks in the code text are removed. -[*][B]Italic text[/B]: surround this text with \`. Example: \`foo\` produces `foo`. -[*][B]Bold text[/B]: surround this text with \[B]text\[\B] tags. Example: \[B]foo\[/B] produces [B]foo[/B]. -[*][B]Text intended to reference a calibre GUI action[/B]. 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` -[*][B]Empty lines[/B], indicated by two newlines in a row. A visible empty line in the FFML -will become an empty line in the output. -[*][B]URLs.[/B] 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] -[*][B]Internal function reference links[/B]. These are links to formatter function -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()``. -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() \` -[*][B]Example program code text blocks.[/B] Surround the code block with ``[CODE]`` -and ``[/CODE]`` tags. These tags must be first on a line. Example: -[CODE] -[CODE] -program: - get_note('authors', 'Isaac Asimov', 1) -[\/CODE] -[/CODE] -produces -[CODE] -program: - get_note('authors', 'Isaac Asimov', 1) -[/CODE] -If you want the literal text ``[/CODE]`` in a code block then it must be entered as ``[\/CODE]`` -to ensure that the FFML parser doesn't interpret it as the end of the code block. The ``'\'`` -character is removed. -[*][B]Bulleted lists[/B], using BBCODE tags. Surround the list with ``[LIST]`` and -``[/LIST]``. List items are indicated with ``[*]``. All of the tags must be -first on a line. Bulleted lists can be nested and can contain other FFML -elements. - -Example: a two bullet list containing CODE blocks -[CODE] -[LIST] -[*]Return the HTML of the note attached to the tag `Fiction`: -[CODE] -program: - get_note('tags', 'Fiction', '') -[\/CODE] -[*]Return the plain text of the note attached to the author `Isaac Asimov`: -[CODE] -program: - get_note('authors', 'Isaac Asimov', 1) -[\/CODE] -[/LIST] -[/CODE] -[*][B]End of summary marker[/B]. A summary is generated from the first characters of -the documentation. The summary includes text up to a \[\/] tag. There is no -opening tag because the summary starts at the first character. If there is -no \[\/] tag then all the document is used for the summary. The \[\/] tag -is removed, not replaced with white space or any other character. -[*][B]Escaped character[/B]: precede the character with a backslash. This is useful -to escape tags. For example to make the \[CODE] tag not a tag, use \\\[CODE]. -Escaping characters doesn't work in `Inline program code text` or -`Example program code text blocks`. -[/LIST] -Note: HTML output contains no CSS and does not start with a tag such as
or

. -''' - - if __name__ == '__main__': from calibre.gui2 import Application app = Application([]) diff --git a/src/calibre/utils/formatter_functions.py b/src/calibre/utils/formatter_functions.py index b48400c3fb..d783911382 100644 --- a/src/calibre/utils/formatter_functions.py +++ b/src/calibre/utils/formatter_functions.py @@ -3789,3 +3789,111 @@ def load_user_template_functions(library_uuid, funcs, precompiled_user_functions def unload_user_template_functions(library_uuid): formatter_functions().unregister_functions(library_uuid) + + +# These are here so they can be processed before sending them to transifex + +general_doc = r''' +[LIST] +[*]`Functions in Single Function Mode templates` +[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 assisting with template function documentation` + +An editor is available for helping write template function documentation. Given a document +in the Formatter Function Markup Language, it show the resulting HTML. The HTML is updated as you edit. + +This editor is available in two ways: +[LIST] +[*]Using the command +[CODE] +calibre-debug -c "from calibre.gui2.dialogs.ff_doc_editor import main; main()"[/CODE] +all on one line. +[*]By defining a keyboard shortcut in calibre for the action `Open the template +documentation editor` in the `Miscellaneous` section. There is no default shortcut. +[/LIST] +[/LIST] +''' + +ffml_doc = r''' +Format Function Markup Language (FFML) is a basic markup language used to +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] +[*][B]Inline program code text[/B]: surround this text with \`\` as in \`\`foo\`\`. +Tags inside the text are ignored. if the code text ends with a `\'` character, put +a space before the closing \`\` characters. Trailing blanks in the code text are removed. +[*][B]Italic text[/B]: surround this text with \`. Example: \`foo\` produces `foo`. +[*][B]Bold text[/B]: surround this text with \[B]text\[\B] tags. Example: \[B]foo\[/B] produces [B]foo[/B]. +[*][B]Text intended to reference a calibre GUI action[/B]. 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` +[*][B]Empty lines[/B], indicated by two newlines in a row. A visible empty line in the FFML +will become an empty line in the output. +[*][B]URLs.[/B] 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] +[*][B]Internal function reference links[/B]. These are links to formatter function +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()``. +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() \` +[*][B]Example program code text blocks.[/B] Surround the code block with ``[CODE]`` +and ``[/CODE]`` tags. These tags must be first on a line. Example: +[CODE] +[CODE] +program: + get_note('authors', 'Isaac Asimov', 1) +[\/CODE] +[/CODE] +produces +[CODE] +program: + get_note('authors', 'Isaac Asimov', 1) +[/CODE] +If you want the literal text ``[/CODE]`` in a code block then it must be entered as ``[\/CODE]`` +to ensure that the FFML parser doesn't interpret it as the end of the code block. The ``'\'`` +character is removed. +[*][B]Bulleted lists[/B], using BBCODE tags. Surround the list with ``[LIST]`` and +``[/LIST]``. List items are indicated with ``[*]``. All of the tags must be +first on a line. Bulleted lists can be nested and can contain other FFML +elements. + +Example: a two bullet list containing CODE blocks +[CODE] +[LIST] +[*]Return the HTML of the note attached to the tag `Fiction`: +[CODE] +program: + get_note('tags', 'Fiction', '') +[\/CODE] +[*]Return the plain text of the note attached to the author `Isaac Asimov`: +[CODE] +program: + get_note('authors', 'Isaac Asimov', 1) +[\/CODE] +[/LIST] +[/CODE] +[*][B]End of summary marker[/B]. A summary is generated from the first characters of +the documentation. The summary includes text up to a \[\/] tag. There is no +opening tag because the summary starts at the first character. If there is +no \[\/] tag then all the document is used for the summary. The \[\/] tag +is removed, not replaced with white space or any other character. +[*][B]Escaped character[/B]: precede the character with a backslash. This is useful +to escape tags. For example to make the \[CODE] tag not a tag, use \\\[CODE]. +Escaping characters doesn't work in `Inline program code text` or +`Example program code text blocks`. +[/LIST] +Note: HTML output contains no CSS and does not start with a tag such as

or

. +'''