=== Bg Highlight Names ===

Contributors: VBog
Donate link: https://bogaiskov.ru/about-me/donate/
Tags: имя, отчество, монах, фамилия, ссылка, книга
Requires PHP: 5.3
Requires at least: 3.0.1
Tested up to: 5.8.2
Stable tag: trunk
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html


Highlight the names in the text

== Description ==

Plugin highlight the names in the text. Supports Russian names (Last, First, MI) and the names of monks.

Плагин подсвечивает имена в тексте статей. Поддерживает русские имена (Фамилия, Имя, Отчество) и имена монахов.

Чтобы не подсвечивать имена в определенной части текста, поместите этот отрывок внутри шорт-кода `[nonames]...[/nonames]`.

= Настройки плагина =

**Режимы работы плагина**

* **онлайн** - В этом режиме плагин выделяет имена лишь тогда, когда текст отображается на экране.
* **оффлайн** - Этот режим делает постоянные изменения в текст при сохранении сообщений.
* **смешенный** - Смесь онлайн и в оффлайн режимов. Подсвечивает имена, когда текст отображается на экране, только если текст не включает в себя ссылки на имена.
* **очистка** - Удаляет ссылки на имена из текста.
* **выкл.** - Плагин не работает (только пакетный режим).

Некоторые поисковые системы воспринимают большое количество одинаковых ссылок как ссылочный спам. Вы можете **ограничеть количество ссылок на человека** в каждом сообщении и статье. 0 - нет ограничений.

В настройках Вы можете выбрать в каком окне **Открывать ссылки** - новом или текущем, или указать имя любого произвального окна.  

Для настройки внешнего вида генерируемых ссылок используйте класс **bg_hlnames**. Вы можете в настройках также указать дополнительный класс для ссылок.

**Максимальное время работы плагина** по умолчанию установлено в 60 секунд. 
Однако, некоторые статьи в Вашем блоге могут быть настолько большими, что этого времени будет не хватать, чтобы проверить на наличие в них всех имен из списка. 
Вы можете подобрать приемлемое для вас максимальное время работы плагина. Установив значение максимального времени равным **0 (ноль)**, Вы полностью снимите ограничение работы скрипта по времени. 
С осторожностью пользуйтесь этой возможностью!  
Обращаю внимание, что если у Вас на сервере php работает в защищенном режиме (safe mode), то эта настройка работать не будет и при обработке больших текстов может возникнуть ошибка (**Fatal error:** Maximum execution time of 30 seconds exceeded in ...). 
Чтобы этого не произошло, плагин сам установит максимальное время своей работы на 1-2 сек. меньше, чем у Вас установлено в настройках php сервера для работы скриптов.

Во время настройки плагина рекомендуется включить опцию **Отображать отладочную информацию в конце поста**. Внешний вид отображаемой информации можно настроить, используя класс **bg_hlnames_debug**.

= Файл данных =

Плагин позволяет использовать различные, заранее подготовленные XML-файлы различного содержания. 
В настоящее время доступны два файла: «Библиотека Святых отцов и церковных писателей» и «Словарь энциклопедии «Азбука веры». 
Файлы хранятся в репозитории WordPress. Чтобы воспользоваться файлом его надо загрузить к себе на сайт. Для этого воспользуйтесь соответствующей опцией **Загрузить XML-файл**.

**Текущий XML-файл**, загруженный из репозитория WordPress на сайт, указан на той же вкладке страницы настроек.

Вы можете использовать собственный **XML-файл имён**. Для этого создайте в MS Excel файл со списком имён, используя XML-схему из файла *schema.xml*, прилагаемого к плагину. 
Структура файла имён подробно описана ниже. Преобразуйте файл из формата Excel в xml. Создание и редактирование XML-файла в Excel описано в [этой статье](https://bogaiskov.ru/xml-excel/). 
Используя ftp-соединение скопируйте полученный xml-файл в любую папку в Вашем блоге и укажите путь этому файлу в настройках плагина.

= Пакетный режим =

**Пакетный режим** - Удаляет ссылки, внесенные в текст при предыдущей обработке, и подсвечивает имена во всех страницах и сообщениях в оффлайн режиме. 
В случае, если включен режим **очистка** пакетный режим только удаляет ссылки из всех статей и сообщений. 
Пакетный режим делает постоянные изменения в текст всех страниц и сообщений, поэтому мы настоятельно рекомендуем сохранить дамп SQL-базы данных, на случай если произойдет сбой в работе плагина.
Процесс обработки может занять весьма продолжительное время (до нескольких часов) и существенно загружает сервер. 
Вы можете обрабатывать посты порциями, указав диапазон порядковых номеров постов в очереди на обработку (по порядку ID).
Рекомендуем на время пакетной обработки отключить доступ к сайту для внешних пользователей.
Во время пакетной обработки не закрывайте вкладку браузера со страницей настроек плагина. 
Результаты пакетной обработки фиксируются в журнале: *parsing.log*, расположенном в папке с файлами плагина.
Файл журнала обновляется при запуске каждой пакетной обработки.
В случае возникновения ошибки обработки поста плагин пытается повторить обработку один раз. 
Если попытка окажется неудачной, плагин переходит к обработке следующего поста. 
Номера необработанных постов фиксируются в файле *parsing_error.log*.

Если Вы хотите добавить новые ссылки, не удаляя старые, включите режим **Не очищать перед обработкой**.


= Структура XML-файла имён =

**name** - Имя человека, склоняется по правилам русского языка

**num** - Приставка к имени, не склоняется. М.б. номер, либо частицы: ст., мл. и т.д.

**nick** - Прозвище (у монахов)

**middlename** - Отчество, склоняется по правилам русского языка (только у мирян)

**surname** - Фамилия. Если в скобках, то у монахов. Или у монахов второе прозвище.

**curacy** - Священнический сан или лик (у монахов) 
	
**sex** - Пол: m - мужской, f -женский
	
**discription** - Описание в свободной форме. Используется во всплывающей подсказке

**lifedates** - Годы жизни через тире. Вторая строка в подсказке

**link** - Ссылка на сайт

= Шаблоны букв в словах списка имён =

**$** - строго 1 любая буква

**%** - 0 или 1 любая буква

**\*** - 0 или несколько любых букв

Если возможны **плавающие буквы** (например, е вместо ё : Пётр - Петра), то указываем оба варианта в квадратных скобках [её]: П[её]тр%%, Ещё пример: Лев - Льва: Л[еь]в%%

**Исчезающая буква**: Святогорец - Святогорца: Святогор(е)?ц%%


= Структура имён =

У всех персон наличие имени обязательно.

= Монахи =

У монаха нет фамилии или фамилия указана в скобках. 

* Если есть Прозвище, то оно обязательно. При этом Сан, второе Прозвище и/или Фамилия необязательны. 
> *архиепископ* Иоанн Шанхайский *(Максимович)*

* Возможно Прозвище в комбинации с Саном. 

	- после имени

	> Иоанн *(Максимович)*, архиепископ Шанхайский
	
	- перед именем

	> *архиепископ* Шанхайский Иоанн *(Максимович)*
 
* Возможны Прозвища в обратной последовательности. 
> *архиепископ* Иоанн (Максимович) *Шанхайский* 

* Если нет прозвища, то обязательна Фамилия. 
> *святитель* Игнатий (Брянчанинов)

* Если нет ни того ни другого обязательно указание Сана (лика).
	- после имени

	> Варнава, апостол 

	- перед именем

	> апостол Варнава
 
* В крайнем случае - только имя с номером. 
> Феликс III

* В исключительных случаях - просто имя. 
> Ерм

= Миряне =

* Фамилия Имя Отчество (отчество не обязательно) 
> Лопухин Александр *Павлович*

* Имя Отчество Фамилия (отчество не обязательно) 
> Александр *Павлович* Лопухин

* Фамилия И. О. (отчество не обязательно) 
> Лопухин А. *П.*

* И. О. Фамилия (отчество не обязательно) 
> А. *П.* Лопухин 

= Важные замечания =

При формировании списка имен необходимо обеспечить уникальность описания персоны.
Для монахов это комбинация Имени и Прозвища (или Фамилии). 

При этом допускается идентификация монахов только по Имени и/или Сану или номеру и в исключительных случаях - только по имени.
Однако, такие случаи следует по возможности избегать и быть крайне внимательным при составлении описания.
(Имя должно быть уникальными располагаться в конце списка имён!!!) 

Для мирян необходимо обеспечить уникальность комбинации Фамилии и инициала Имени.

== Screenshots ==

1. Общие настройки плагина.
2. Управление файлом данных.
3. Пакетный режим работы плагина.

== Installation ==

Для установки плагина сделайте три простых шага:

1. Скачайте архив плагина и распакуйте его.
2. Используя ftp-соединение скопируйте файлы плагина в папку ` /wp-content/plugins/bg-highlight-names/ `.
3. После загрузки активируйте плагин из меню плагинов WordPress.

== Frequently Asked Questions ==

**Вопрос:** При пакетной обработке возникла ошибка и кнопка "Разбор всех постов" осталась недоступной. Что делать?

**Ответ:** Деактивируйте плагин, а затем заново активируйте его на странице плагинов.

**Вопрос:** В чем причина ошибки **Fatal error:** Maximum execution time of ... seconds exceeded in... ?

**Ответ:** Эта ошибка может возникнуть, если время максимально допустимое время работы скрипта меньше, чем время необходимое для обработки одного поста. Увеличьте Максимальное время работы плагина.

**Вопрос:** У меня пакетная обработка всех постов занимает несколько часов времен. Неужели при добавлении нового имени нужно заново повторить весь процесс обработки?

**Ответ:** Если необходимо добавить новые имена, не спешите их добавлять в основной файл *data.xml*. Сначала создайте файл только с новыми авторами, разместите его где-нибудь на сервере и укажите его *url* в настройках и проведите обработку.  Добавление произойдет как минимум в 400 раз быстрее!


== Changelog ==

= 1.2.1-5 =

* Дополнен файл данных "Библиотека Святых отцов и церковных писателей".
* Исправлены некоторые ошибки.

= 1.2 =

* Добавлен шорт-код [nonames]...[/nonames].
* Дополнен файл данных "Библиотека Святых отцов и церковных писателей".

= 1.1 =

* Добавлена возможность загружать XML-файл из репозитория WordPress.

= 1.0 =

* Первая публичная версия

== Upgrade Notice ==

= 1.1 =

* Добавлена возможность загружать XML-файл из репозитория WordPress.

= 1.0 =

Первая публичная версия