Debian Codegraph @

translations/manual/function_mode.pot

raw
1 # SOME DESCRIPTIVE TITLE.
2 # Copyright (C) Kovid Goyal
3 # This file is distributed under the same license as the calibre package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
5 #
6 #, fuzzy
7 msgid ""
8 msgstr ""
9 "Project-Id-Version: calibre 9.15.0\n"
10 "Report-Msgid-Bugs-To: \n"
11 "POT-Creation-Date: 2026-09-18 07:37+0530\n"
12 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
13 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
14 "Language-Team: LANGUAGE <[email protected]>\n"
15 "MIME-Version: 1.0\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
18
19 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:2
20 msgid "Function mode for Search & replace in the Editor"
21 msgstr ""
22
23 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:4
24 msgid "The :guilabel:`Search & replace` tool in the editor supports a *function mode*. In this mode, you can combine regular expressions (see :doc:`regexp`) with arbitrarily powerful Python functions to do all sorts of advanced text processing."
25 msgstr ""
26
27 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:9
28 msgid "In the standard *regexp* mode for search and replace, you specify both a regular expression to search for as well as a template that is used to replace all found matches. In function mode, instead of using a fixed template, you specify an arbitrary function, in the `Python programming language <https://docs.python.org>`_. This allows you to do lots of things that are not possible with simple templates."
29 msgstr ""
30
31 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:16
32 msgid "Techniques for using function mode and the syntax will be described by means of examples, showing you how to create functions to perform progressively more complex tasks."
33 msgstr ""
34
35 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:21
36 msgid "The Function mode"
37 msgstr ""
38
39 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:26
40 msgid "Automatically fixing the case of headings in the document"
41 msgstr ""
42
43 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:28
44 msgid "Here, we will leverage one of the builtin functions in the editor to automatically change the case of all text inside heading tags to title case::"
45 msgstr ""
46
47 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:33
48 msgid "For the function, simply choose the :guilabel:`Title-case text (ignore tags)` builtin function. This will change titles that look like: ``<h1>some titLE</h1>`` to ``<h1>Some Title</h1>``. It will work even if there are other HTML tags inside the heading tags."
49 msgstr ""
50
51 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:40
52 msgid "Your first custom function - smartening hyphens"
53 msgstr ""
54
55 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:42
56 msgid "The real power of function mode comes from being able to create your own functions to process text in arbitrary ways. The Smarten Punctuation tool in the editor leaves individual hyphens alone, so you can use this function to replace them with em-dashes."
57 msgstr ""
58
59 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:47
60 msgid "To create a new function, simply click the :guilabel:`Create/edit` button to create a new function and copy the Python code from below."
61 msgstr ""
62
63 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:55
64 msgid "Every :guilabel:`Search & replace` custom function must have a unique name and consist of a Python function named replace, that accepts all the arguments shown above. For the moment, we won't worry about all the different arguments to ``replace()`` function. Just focus on the ``match`` argument. It represents a match when running a search and replace. Its full documentation in available `here <https://docs.python.org/library/re.html#match-objects>`_. ``match.group()`` simply returns all the matched text and all we do is replace hyphens in that text with em-dashes, first replacing double hyphens and then single hyphens."
65 msgstr ""
66
67 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:65
68 msgid "Use this function with the find regular expression::"
69 msgstr ""
70
71 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:69
72 msgid "And it will replace all hyphens with em-dashes, but only in actual text and not inside HTML tag definitions."
73 msgstr ""
74
75 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:74
76 msgid "The power of function mode - using a spelling dictionary to fix mis-hyphenated words"
77 msgstr ""
78
79 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:76
80 msgid "Often, e-books created from scans of printed books contain mis-hyphenated words -- words that were split at the end of the line on the printed page. We will write a simple function to automatically find and fix such words."
81 msgstr ""
82
83 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:101
84 msgid "Use this function with the same find expression as before, namely::"
85 msgstr ""
86
87 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:105
88 msgid "And it will magically fix all mis-hyphenated words in the text of the book. The main trick is to use one of the useful extra arguments to the replace function, ``dictionaries``. This refers to the dictionaries the editor itself uses to spell check text in the book. What this function does is look for words separated by a hyphen, remove the hyphen and check if the dictionary recognizes the composite word, if it does, the original words are replaced by the hyphen free composite word."
89 msgstr ""
90
91 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:113
92 msgid "Note that one limitation of this technique is it will only work for mono-lingual books, because, by default, ``dictionaries.recognized()`` uses the main language of the book."
93 msgstr ""
94
95 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:119
96 msgid "Auto numbering sections"
97 msgstr ""
98
99 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:121
100 msgid "Now we will see something a little different. Suppose your HTML file has many sections, each with a heading in an :code:`<h2>` tag that looks like :code:`<h2>Some text</h2>`. You can create a custom function that will automatically number these headings with consecutive section numbers, so that they look like :code:`<h2>1. Some text</h2>`."
101 msgstr ""
102
103 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:137
104 msgid "Use it with the find expression::"
105 msgstr ""
106
107 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:141
108 msgid "Place the cursor at the top of the file and click :guilabel:`Replace all`."
109 msgstr ""
110
111 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:143
112 msgid "This function uses another of the useful extra arguments to ``replace()``: the ``number`` argument. When doing a :guilabel:`Replace All` number is automatically incremented for every successive match."
113 msgstr ""
114
115 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:147
116 msgid "Another new feature is the use of ``replace.file_order`` -- setting that to ``'spine'`` means that if this search is run on multiple HTML files, the files are processed in the order in which they appear in the book. See :ref:`file_order_replace_all` for details."
117 msgstr ""
118
119 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:154
120 msgid "Auto create a Table of Contents"
121 msgstr ""
122
123 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:156
124 msgid "Finally, let's try something a little more ambitious. Suppose your book has headings in ``h1`` and ``h2`` tags that look like ``<h1 id=\"someid\">Some Text</h1>``. We will auto-generate an HTML Table of Contents based on these headings. Create the custom function below:"
125 msgstr ""
126
127 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:199
128 msgid "And use it with the find expression::"
129 msgstr ""
130
131 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:203
132 msgid "Run the search on :guilabel:`All text files` and at the end of the search, a window will popup with \"Debug output from your function\" which will have the HTML Table of Contents, ready to be pasted into :file:`toc.html`."
133 msgstr ""
134
135 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:207
136 msgid "The function above is heavily commented, so it should be easy to follow. The key new feature is the use of another useful extra argument to the ``replace()`` function, the ``data`` object. The ``data`` object is a Python *dictionary* that persists between all successive invocations of ``replace()`` during a single :guilabel:`Replace All` operation."
137 msgstr ""
138
139 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:213
140 msgid "Another new feature is the use of ``call_after_last_match`` -- setting that to ``True`` on the ``replace()`` function means that the editor will call ``replace()`` one extra time after all matches have been found. For this extra call, the match object will be ``None``."
141 msgstr ""
142
143 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:218
144 msgid "This was just a demonstration to show you the power of function mode, if you really needed to generate a Table of Contents from headings in your book, you would be better off using the dedicated Table of Contents tool in :guilabel:`Tools->Table of Contents`."
145 msgstr ""
146
147 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:224
148 msgid "The API for the function mode"
149 msgstr ""
150
151 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:226
152 msgid "All function mode functions must be Python functions named replace, with the following signature::"
153 msgstr ""
154
155 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:232
156 msgid "When a find/replace is run, for every match that is found, the ``replace()`` function will be called, it must return the replacement string for that match. If no replacements are to be done, it should return ``match.group()`` which is the original string. The various arguments to the ``replace()`` function are documented below."
157 msgstr ""
158
159 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:239
160 msgid "The ``match`` argument"
161 msgstr ""
162
163 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:241
164 msgid "The ``match`` argument represents the currently found match. It is a `Python Match object <https://docs.python.org/library/re.html#match-objects>`_. Its most useful method is ``group()`` which can be used to get the matched text corresponding to individual capture groups in the search regular expression."
165 msgstr ""
166
167 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:248
168 msgid "The ``number`` argument"
169 msgstr ""
170
171 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:250
172 msgid "The ``number`` argument is the number of the current match. When you run :guilabel:`Replace All`, every successive match will cause ``replace()`` to be called with an increasing number. The first match has number 1."
173 msgstr ""
174
175 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:255
176 msgid "The ``file_name`` argument"
177 msgstr ""
178
179 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:257
180 msgid "This is the filename of the file in which the current match was found. When searching inside marked text, the ``file_name`` is empty. The ``file_name`` is in canonical form, a path relative to the root of the book, using ``/`` as the path separator."
181 msgstr ""
182
183 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:263
184 msgid "The ``metadata`` argument"
185 msgstr ""
186
187 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:265
188 msgid "This represents the metadata of the current book, such as title, authors, language, etc. It is an object of class :class:`calibre.ebooks.metadata.book.base.Metadata`. Useful attributes include, ``title``, ``authors`` (a list of authors) and ``language`` (the language code)."
189 msgstr ""
190
191 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:271
192 msgid "The ``dictionaries`` argument"
193 msgstr ""
194
195 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:273
196 msgid "This represents the collection of dictionaries used for spell checking the current book. Its most useful method is ``dictionaries.recognized(word)`` which will return ``True`` if the passed in word is recognized by the dictionary for the current book's language."
197 msgstr ""
198
199 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:279
200 msgid "The ``data`` argument"
201 msgstr ""
202
203 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:281
204 msgid "This a simple Python ``dictionary``. When you run :guilabel:`Replace all`, every successive match will cause ``replace()`` to be called with the same ``dictionary`` as data. You can thus use it to store arbitrary data between invocations of ``replace()`` during a :guilabel:`Replace all` operation."
205 msgstr ""
206
207 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:288
208 msgid "The ``functions`` argument"
209 msgstr ""
210
211 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:290
212 msgid "The ``functions`` argument gives you access to all other user defined functions. This is useful for code re-use. You can define utility functions in one place and re-use them in all your other functions. For example, suppose you create a function named ``My Function`` like this:"
213 msgstr ""
214
215 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:303
216 msgid "Then, in another function, you can access the ``utility()`` function like this:"
217 msgstr ""
218
219 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:311
220 msgid "You can also use the functions object to store persistent data, that can be re-used by other functions. For example, you could have one function that when run with :guilabel:`Replace All` collects some data and another function that uses it when it is run afterwards. Consider the following two functions:"
221 msgstr ""
222
223 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:331
224 msgid "Debugging your functions"
225 msgstr ""
226
227 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:333
228 msgid "You can debug the functions you create by using the standard ``print()`` function from Python. The output of print will be displayed in a popup window after the Find/replace has completed. You saw an example of using ``print()`` to output an entire table of contents above."
229 msgstr ""
230
231 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:341
232 msgid "Choose file order when running on multiple HTML files"
233 msgstr ""
234
235 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:343
236 msgid "When you run a :guilabel:`Replace all` on multiple HTML files, the order in which the files are processed depends on what files you have open for editing. You can force the search to process files in the order in which they appear by setting the ``file_order`` attribute on your function, like this:"
237 msgstr ""
238
239 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:355
240 msgid "``file_order`` accepts two values, ``spine`` and ``spine-reverse`` which cause the search to process multiple files in the order they appear in the book, either forwards or backwards, respectively."
241 msgstr ""
242
243 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:360
244 msgid "Having your function called an extra time after the last match is found"
245 msgstr ""
246
247 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:362
248 msgid "Sometimes, as in the auto generate table of contents example above, it is useful to have your function called an extra time after the last match is found. You can do this by setting the ``call_after_last_match`` attribute on your function, like this:"
249 msgstr ""
250
251 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:376
252 msgid "Appending the output from the function to marked text"
253 msgstr ""
254
255 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:378
256 msgid "When running search and replace on marked text, it is sometimes useful to append some text to the end of the marked text. You can do that by setting the ``append_final_output_to_marked`` attribute on your function (note that you also need to set ``call_after_last_match``), like this:"
257 msgstr ""
258
259 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:393
260 msgid "Suppressing the result dialog when performing searches on marked text"
261 msgstr ""
262
263 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:395
264 msgid "You can also suppress the result dialog (which can slow down the repeated application of a search/replace on many blocks of text) by setting the ``suppress_result_dialog`` attribute on your function, like this:"
265 msgstr ""
266
267 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:408
268 msgid "More examples"
269 msgstr ""
270
271 #: ../../../home/kovid/work/calibre/manual/function_mode.rst:410
272 msgid "More useful examples, contributed by calibre users, can be found in the `calibre E-book editor forum <https://www.mobileread.com/forums/showthread.php?t=237181>`_."
273 msgstr ""