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