calibre - en to ru translation catalogue (63 entries)

en: Function mode for Search & replace in the Editor
ru: Функциональный режим для поиска и замены в редакторе

en: 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.
ru: Инструмент :guilabel:`Search & replace` в редакторе поддерживает *функциональный режим*. В этом режиме вы можете комбинировать регулярные выражения (см. :doc:`regexp`) с произвольно мощными функциями Python для выполнения всех видов расширенной обработки текста.

en: 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.
ru: В стандартном режиме *regexp* для поиска и замены вы указываете как регулярное выражение для поиска, так и шаблон, который используется для замены всех найденных совпадений. В функциональном режиме вместо использования фиксированного шаблона вы указываете произвольную функцию на `языке программирования Python <https://docs.python.org/>`_. Это позволяет вам делать много вещей, которые невозможны с простыми шаблонами.

en: 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.
ru: Методы использования функционального режима и синтаксиса будут описаны с помощью примеров, показывающих, как создавать функции для выполнения более сложных задач.

en: The Function mode
ru: Функциональный режим

en: Automatically fixing the case of headings in the document
ru: Автоматическое исправление регистра заголовков в документе

en: 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::
ru: Здесь мы будем использовать одну из встроенных функций в редакторе, чтобы автоматически изменять регистр всего текста внутри тегов заголовка на регистр заголовка::

en: Your first custom function - smartening hyphens
ru: Ваша первая пользовательская функция - умные дефисы

en: 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.
ru: Настоящая сила режима функций заключается в возможности создавать свои собственные функции для произвольной обработки текста. Инструмент Smarten Punctuation в редакторе оставляет индивидуальные дефисы в отдельности, поэтому вы можете использовать эту функцию, чтобы заменить их на тире.

en: To create a new function, simply click the :guilabel:`Create/edit` button to create a new function and copy the Python code from below.
ru: Чтобы создать новую функцию, просто нажмите кнопку :guilabel:`Create/edit`, чтобы создать новую функцию и скопировать код Python снизу.

en: 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.
ru: Каждая пользовательская функция :guilabel:`Search & replace` должна иметь уникальное имя и состоять из функции Python с именем replace, которая принимает все аргументы, показанные выше. На данный момент мы не будем беспокоиться о различных аргументах функции ``replace()``. Просто сосредоточьтесь на аргументе ``match``. Он представляет совпадение при выполнении поиска и замены. Полная документация доступна `здесь https://docs.python.org/library/re.html#match-objects`_. ``match.group()`` просто возвращает весь совпавший текст, и всё, что мы делаем, это заменяем дефисы в этом тексте длинными тире, сначала заменяя двойные дефисы, а затем одиночные дефисы.

en: Use this function with the find regular expression::
ru: Используйте эту функцию с регулярным выражением поиска::

en: And it will replace all hyphens with em-dashes, but only in actual text and not inside HTML tag definitions.
ru: И он заменит все дефисы на тире, но только в реальном тексте, а не в определениях тегов HTML.

en: The power of function mode - using a spelling dictionary to fix mis-hyphenated words
ru: Сила функционального режима - использование орфографического словаря для исправления неверно написанных слов

en: 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.
ru: Часто электронные книги, созданные на основе отсканированных печатных книг, содержат неправильно написанные слова - слова, которые были разбиты в конце строки на печатной странице. Мы напишем простую функцию для автоматического поиска и исправления таких слов.

en: Use this function with the same find expression as before, namely::
ru: Используйте эту функцию с тем же выражением поиска, что и раньше, а именно::

en: 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.
ru: И это волшебным образом исправит все неправильно написанные слова в тексте книги. Основная хитрость заключается в использовании одного из полезных дополнительных аргументов для функции замены, ``словарей``. Это относится к словарям, которые сам редактор использует для проверки правописания текста в книге. Эта функция ищет слова, разделенные дефисом, удаляет дефис и проверяет, распознает ли словарь составное слово; если да, то исходные слова заменяются составным словом без дефиса.

en: 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.
ru: Обратите внимание, что одним из ограничений этой техники является то, что она будет работать только для одноязычных книг, потому что по умолчанию ``dictionaries.recognized()`` использует основной язык книги.

en: Auto numbering sections
ru: Авто нумерация разделов

en: 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>`.
ru: Теперь мы увидим что-то немного другое. Предположим, ваш HTML-файл имеет много разделов, каждый из которых имеет заголовок в  :code:`<h2>` теге, который выглядит следующим образом :code: `<h2>Some text</h2>`. Вы можете создать пользовательскую функцию, которая будет автоматически нумеровать эти заголовки последовательными номерами разделов, чтобы они выглядели так :code:`<h2>1. Some text</h2>`.

en: Use it with the find expression::
ru: Используйте это с выражением поиска::

en: Place the cursor at the top of the file and click :guilabel:`Replace all`.
ru: Поместите курсор вверху файла и нажмите :guilabel:`Заменить все`.

en: 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.
ru: Эта функция использует еще один полезный дополнительный аргумент для ``replace()``: аргумент `` number``. При выполнении :guilabel:`Заменить все` номер автоматически увеличивается для каждого последующего совпадения.

en: 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.
ru: Другой новой функцией является использование ``replace.file_order`` - установка этого значения в ``'spine'`` означает, что если этот поиск выполняется по нескольким HTML-файлам, файлы обрабатываются в том порядке, в котором они отображаются в книга. Смотрите :ref:`file_order_replace_all` для деталей.

en: Auto create a Table of Contents
ru: Автоматическое создание оглавления

en: Finally, lets 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:
ru: Наконец, давайте попробуем что-нибудь более амбициозное. Предположим, что ваша книга имеет заголовки в тегах ``h1`` и ``h2``, которые выглядят как ``<h1 id="someid">Some Text</h1>``. Мы автоматически сгенерируем оглавление HTML на основе этих заголовков. Создайте пользовательскую функцию ниже:

en: And use it with the find expression::
ru: И использовать это с выражением поиска::

en: 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`.
ru: Запустите поиск по :guilabel:`Все текстовые файлы` и в конце поиска появится окно Отладка вывода из вашей функции, которое будет содержать оглавление HTML, готовое для вставки в :file:`toc.html`.

en: 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.
ru: Вышеприведенная функция сильно прокомментирована, поэтому ей должно быть легко следовать. Ключевой новой возможностью является использование другого полезного дополнительного аргумента для функции ``replace()`` объекта ``data``. Объект ``data`` - это Python *dict*, который сохраняется между всеми последовательными вызовами ``replace()``во время одной операции :guilabel:`Replace All`.

en: 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``.
ru: Еще одной новой возможностью является использование ``call_after_last_match`` - установка этого параметра в `` True`` в функции ` replace()`` означает, что редактор будет вызывать ``replace()`` один раз после всех найденных совпадений. Для этого дополнительного вызова объектом сопоставления будет ``None``.

en: 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`.
ru: Это была просто демонстрация мощи функционального режима: если вам действительно нужно сгенерировать оглавление из заголовков в вашей книге, вам лучше использовать специальный инструмент оглавления в :guilabel:`Инструменты->Оглавление.

en: The API for the function mode
ru: API для function mode

en: All function mode functions must be Python functions named replace, with the following signature::
ru: Все функции function mode должны быть функциями Python с именем replace, со следующей сигнатурой::

en: 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.
ru: Когда выполняется поиск/замена, для каждого найденного совпадения вызывается функция ``replace()``, она должна возвращать строку замены для этого совпадения. Если никакие замены не должны быть сделаны, она должна вернуть ``match.group()``, которая является исходной строкой. Различные аргументы функции ``replace()`` описаны ниже.

en: The ``match`` argument
ru: Аргумент ``match``

en: 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.
ru: Аргумент ``match`` представляет текущее найденное совпадение. Это объект `Python Match <https://docs.python.org/library/re.html#match-objects>`_. Его наиболее полезным методом является ``group()``, который можно использовать для получения сопоставленного текста, соответствующего отдельным группам захвата в регулярном выражении поиска.

en: The ``number`` argument
ru: Аргумент ``number``

en: 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.
ru: Аргумент ``number`` - это номер текущего совпадения. Когда вы запускаете :guilabel:`Replace All`, каждое последующее совпадение будет вызывать``replace()`` с возрастающим числом. Первое совпадение имеет номер 1.

en: The ``file_name`` argument
ru: Аргумент ``file_name``

en: 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.
ru: Это имя файла, в котором было найдено текущее совпадение. При поиске внутри помеченного текста ``file_name`` пусто. ``file_name`` находится в канонической форме, пути относительно корня книги, используя ``/`` в качестве разделителя пути.

en: The ``metadata`` argument
ru: Аргумент ``metadata``

en: 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).
ru: Это представляет метаданные текущей книги, такие как название, авторы, язык и т. д. Это объект класса :class:`calibre.ebooks.metadata.book.base.Metadata`. Полезные атрибуты включают ``title``, ``authors`` (список авторов) и ``language`` (код языка).

en: The ``dictionaries`` argument
ru: Аргумент ``dictionaries``

en: 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.
ru: Это представляет собой словари, используемые для проверки орфографии текущей книги. Его наиболее полезным методом является ``dictionaries.recognized(word)``, который будет возвращать ``True``, если переданное слово распознается словарём для языка текущей книги.

en: The ``data`` argument
ru: Аргумент ``data``

en: 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.
ru: Это простой Python ``dict``. Когда вы запускаете :guilabel:`Replace all`, каждое последующее совпадение будет вызывать``replace()`` с тем же ``dict``, что и для данных. Таким образом, вы можете использовать его для хранения произвольных данных между вызовами ``replace()`` во время операции :guilabel:`Replace all`.

en: The ``functions`` argument
ru: Аргумент ``functions``

en: 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:
ru: Аргумент ``functions`` предоставляет вам доступ ко всем другим пользовательским функциям. Это полезно для повторного использования кода. Вы можете определить служебные функции в одном месте и повторно использовать их во всех других ваших функциях. Например, предположим, что вы создаете имя функции ``My Function`` следующим образом:

en: Then, in another function, you can access the ``utility()`` function like this:
ru: Затем в другой функции вы можете получить доступ к функции ``utility()`` следующим образом:

en: 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:
ru: Вы также можете использовать объект функций для хранения постоянных данных, которые могут быть повторно использованы другими функциями. Например, у вас может быть одна функция, которая при запуске с :guilabel:`Replace All` собирает некоторые данные, и другая функция, которая использует их при последующем запуске. Рассмотрим следующие две функции:

en: Debugging your functions
ru: Отладка ваших функций

en: 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.
ru: Вы можете отлаживать созданные вами функции, используя стандартную функцию ``print()`` из Python. Результат печати будет отображаться во всплывающем окне после завершения поиска/замены. Вы видели пример использования ``print()`` для вывода всего оглавления выше.

en: Choose file order when running on multiple HTML files
ru: Выберите порядок файлов при работе с несколькими файлами HTML

en: 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:
ru: Когда вы запускаете :guilabel:`Заменить все` для нескольких файлов HTML, порядок, в котором файлы обрабатываются, зависит от того, какие файлы вы открыли для редактирования. Вы можете заставить поиск обрабатывать файлы в том порядке, в котором они отображаются, установив атрибут ``file_order`` в вашей функции, например так:

en: ``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.
ru: ``file_order`` принимает два значения, ``spine`` и ``spine-reverse``, которые заставляют поиск обрабатывать несколько файлов в порядке их появления в книге, либо вперед, либо назад, соответственно.

en: Having your function called an extra time after the last match is found
ru: Вызов вашей функции дополнительно после нахождения последнего совпадения

en: 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:
ru: Иногда, как в приведенном выше примере с автоматическим созданием оглавления, полезно, чтобы ваша функция вызывалась дополнительно после того, как найдено последнее совпадение. Вы можете сделать это, установив атрибут ``call_after_last_match`` в вашей функции, например так:

en: Appending the output from the function to marked text
ru: Добавление вывода из функции к выделенному тексту

en: 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:
ru: При поиске и замене отмеченного текста иногда бывает полезно добавить такой текст в конец отмеченного текста. Вы можете сделать это, установив атрибут ``append_final_output_to_marked`` в своей функции (обратите внимание, что вам также необходимо установить ``call_after_last_match``), например так:

en: Suppressing the result dialog when performing searches on marked text
ru: Подавление диалогового окна результатов при выполнении поиска по выделенному тексту

en: 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:
ru: Вы также можете отключить диалоговое окно результатов (которое может замедлить повторное применение поиска/замены во многих блоках текста), установив атрибут ``suppress_result_dialog`` в вашей функции, например так:

en: More examples
ru: Больше примеров

en: 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>`_.
ru: Больше полезных примеров от пользователей calibre можно найти на `форуме редактора calibre <https://www.mobileread.com/forums/showthread.php?t=237181>`_.
