Автоматические проверки

Команда sobiraka prover проверяет текст всего документа и сообщает о найденных ошибках.

Перед выполнением проверок Собирака конвертирует каждую страницу в простой текст без ссылок и форматирования. В текст не включается содержимое элементов, перечисленных в настройке prover.skip_elements (например, так можно отключить проверку внутри блоков кода). После этого независимо друг от друга выполняются различные проверки качества текста. В работе проверок используются словари, добавленные для вашего проекта. Все найденные ошибки выводятся в консоль.

Поддерживаются следующие форматы словарей:

• словари Hunspell (файлы *.dic и *.aff),
• простые текстовые словари (файлы *.txt),
• словари с регулярными выражениями (файлы *.regexp).

Обратите внимание, что автоматические проверки не заменяют полноценную редактуру текста, а лишь упрощают её. Настоящие редакторы имеют человеческую форму и работают в Documentat.

Проверки #

Проверка орфографии #

Собирака может сопоставлять слова в вашем тексте с одним или несколькими словарями. Если слово не найдено ни в одном, это считается ошибкой: в таком случае нужно исправить текст либо добавить недостающее слово в один из словарей проекта.

Технически эта проверка состоит из двух этапов:

1. Поиск фрагментов, совпадающих с записями из простых текстовых словарей или словарей с регулярными выражениями, среди всего текста.
2. Поиск фрагментов, совпадающих с записями из словарей Hunspell, среди оставшегося текста.

Чтобы проверка заработала, укажите один или несколько словарей в настройке prover.dictionaries, при этом среди них должен быть хотя бы один словарь Hunspell.

Проверка заглавных букв в начале фраз #

Эта проверка делит текст на фразы по точкам и другим знакам препинания и проверяет, чтобы каждая фраза начиналась с заглавной буквы. Нарушения этого правила допускаются только в нескольких случаях:

• фраза находится в списке, перед которым стояло двоеточие (прямо как перед этим списком!);
• фраза начинается с инлайнового фрагмента кода (было бы некорректно исправлять первую букву во фразе «bool это тип переменной»);
• фраза начинается со слова из простого текстового словаря или словаря с регулярными выражениями (если там есть слово «iPhone», то такое написание должно быть допустимо даже в начале фразы).

Чтобы проверка заработала, включите настройку prover.phrases_must_begin_with_capitals.

Проверка кавычек и апострофов #

Эта проверка находит в тексте кавычки и апострофы, не соответствующие стилю проекта. Например, с её помощью вы можете вовремя заметить случайное использование ” вместо “.

Также выполняется проверка парности кавычек. Например, такой „фрагмент текста» считается некорректным, поскольку открывающая и закрывающая кавычки не соответствуют друг другу. Также некорректным будет такой „фрагмент текста, если после него нет закрывающей кавычки на той же строке.

В зависимости от настроек символы ’ и ' могут интерпретироваться либо как кавычки (части пар ‘ ’ и ' '), либо как апострофы. В последнем случае они игнорируются при анализе парности кавычек.

Чтобы проверка заработала, укажите допустимые начертания кавычек в настройке prover.allowed_quotation_marks и, опционально, допустимые начертания апострофов в настройке prover.allowed_apostrophes.

Словари #

Словари Hunspell #

Основную часть работы по проверке орфографии Собирака поручает популярному инструменту Hunspell. Он корректно распознаёт большинство слов с помощью специальных файлов-словарей. Если какие-то слова были не распознаны, Собирака выводит их список в своём сообщении об ошибке.

Словарь для Hunspell обычно представляет собой пару файлов *.dic и *.aff, реже — один файл *.dic. Указывать в настройке нужно путь к файлу *.dic, а соответствующий ему файл *.aff загрузится сам.

Мы рекомендуем скачать готовые словари из интернета или использовать словари, поставляемые с Собиракой: для этого вместо пути к файлу напишите просто russian или english. Можно также составить свой собственный словарь: туда имеет смысл включить название продукта, сленг из вашей предметной области и тому подобное. Например, в словарь для проверки документации, которую вы сейчас читаете, добавлено слово «Собирака» и указаны допустимые формы его склонения.

Формат словарей для Hunspell описан в официальной документации: hunspell(5). К сожалению, этот формат не очень интуитивен, и при редактировании легко ошибиться и получить некорректный файл. Встроенная в Собираку команда validate_dictionary может починить файл автоматически в некоторых случаях, но все нюансы она проверить не может (автор Собираки всех нюансов не знает). Когда возможно, рекомендуется добавлять новые слова в словари других форматов — с ними проще работать.

Простые текстовые словари #

Файлы с расширением *.txt интерпретируются как простые списки слов или целых фраз, употребление которых не считается ошибкой. В отличие от словарей Hunspell, эти словари могут содержать записи с любыми символами, включая точки и пробелы. Например, если добавить строчку «и т.п.», то Собирака не будет считать эту конкретную последовательность символов ошибкой, даже если отдельных слов «т» и «п» в словаре нет.

Чтобы фрагмент текста совпал с записью из словаря, его начало и конец должны приходится на границы слов. Говоря технически, запись Documentat в текстовом словаре работает идентично записи \bDocumentat\b в словаре с регулярными выражениями (см. далее).

Словари с регулярными выражениями #

Файлы с расширением *.regexp интерпретируются как списки регулярных выражений. Как и простые текстовые выражения, они могут соответствовать наборам символов, включающим пробелы, точки и любые другие символы. Но, в отличие от записей из простых текстовых словарей, границы найденных фрагментов могут проходить где угодно, в том числе посередине слов. Когда такое поведение нежелательно, добавляйте \b в начале и конце регулярных выражений.