# SOME DESCRIPTIVE TITLE. # Copyright (C) Kovid Goyal # This file is distributed under the same license as the calibre package. # # Translators: # Robert Antoni Buj i Gelonch , 2016 msgid "" msgstr "" "Project-Id-Version: calibre\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2021-10-07 03:23+0000\n" "PO-Revision-Date: 2021-10-03 01:41+0000\n" "Last-Translator: Kovid Goyal \n" "Language-Team: Catalan (http://www.transifex.com/calibre/calibre/language/ca/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Language: ca\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" #: ../../__w/calibre/calibre/manual/function_mode.rst:2 msgid "Function mode for Search & replace in the Editor" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:4 msgid "" "The :guilabel:`Search & replace` tool in the editor support 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:9 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 `_. This allows you to do lots of things " "that are not possible with simple templates." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:16 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rstNone msgid "The Function mode" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:26 msgid "Automatically fixing the case of headings in the document" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:28 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::" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:33 msgid "" "For the function, simply choose the :guilabel:`Title-case text (ignore " "tags)` builtin function. The will change titles that look like: ``

some " "TITLE

`` to ``

Some Title

``. It will work even if there are " "other HTML tags inside the heading tags." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:40 msgid "Your first custom function - smartening hyphens" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:42 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 the this " "function to replace them with em-dashes." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:47 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:55 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 `_. ``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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:65 msgid "Use this function with the find regular expression::" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:69 msgid "" "And it will replace all hyphens with em-dashes, but only in actual text and " "not inside HTML tag definitions." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:74 msgid "" "The power of function mode - using a spelling dictionary to fix mis-" "hyphenated words" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:76 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:101 msgid "Use this function with the same find expression as before, namely::" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:105 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:113 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:119 msgid "Auto numbering sections" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:121 msgid "" "Now we will see something a little different. Suppose your HTML file has " "many sections, each with a heading in an :code:`

` tag that looks like " ":code:`

Some text

`. You can create a custom function that will " "automatically number these headings with consecutive section numbers, so " "that they look like :code:`

1. Some text

`." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:137 msgid "Use it with the find expression::" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:141 msgid "" "Place the cursor at the top of the file and click :guilabel:`Replace all`." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:143 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:147 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:154 msgid "Auto create a Table of Contents" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:156 msgid "" "Finally, lets try something a little more ambitious. Suppose your book has " "headings in ``h1`` and ``h2`` tags that look like ``

Some " "Text

``. We will auto-generate an HTML Table of Contents based on these " "headings. Create the custom function below:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:199 msgid "And use it with the find expression::" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:203 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`." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:207 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" " *dict* that persists between all successive invocations of ``replace()`` " "during a single :guilabel:`Replace All` operation." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:213 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``." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:218 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`." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:224 msgid "The API for the function mode" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:226 msgid "" "All function mode functions must be Python functions named replace, with the" " following signature::" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:232 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:239 msgid "The ``match`` argument" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:241 msgid "" "The ``match`` argument represents the currently found match. It is a `Python" " Match object `_. 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:248 msgid "The ``number`` argument" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:250 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:255 msgid "The ``file_name`` argument" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:257 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:263 msgid "The ``metadata`` argument" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:265 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)." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:271 msgid "The ``dictionaries`` argument" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:273 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:279 msgid "The ``data`` argument" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:281 msgid "" "This a simple Python ``dict``. When you run :guilabel:`Replace all`, every " "successive match will cause ``replace()`` to be called with the same " "``dict`` as data. You can thus use it to store arbitrary data between " "invocations of ``replace()`` during a :guilabel:`Replace all` operation." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:288 msgid "The ``functions`` argument" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:290 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 name ``My Function`` like this:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:303 msgid "" "Then, in another function, you can access the ``utility()`` function like " "this:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:311 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:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:331 msgid "Debugging your functions" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:333 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:341 msgid "Choose file order when running on multiple HTML files" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:343 msgid "" "When you run a :guilabel:`Replace all` on multiple HTML files, the order in " "which the files are processes depends on what files you have open for " "editing. You can force the search to process files in the order in which the" " appear by setting the ``file_order`` attribute on your function, like this:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:355 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." msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:360 msgid "" "Having your function called an extra time after the last match is found" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:362 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:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:376 msgid "Appending the output from the function to marked text" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:378 msgid "" "When running search and replace on marked text, it is sometimes useful to " "append so 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:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:393 msgid "Suppressing the result dialog when performing searches on marked text" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:395 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:" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:408 msgid "More examples" msgstr "" #: ../../__w/calibre/calibre/manual/function_mode.rst:410 msgid "" "More useful examples, contributed by calibre users, can be found in the " "`calibre E-book editor forum " "`_." msgstr ""