Автоматическая проверка орфографии для систем генерирования справочной документации на примере AsciiDoc, NovellDoc и OpenSuse.

В своем проекте я использую программу (скрипт) Asciidoc для формирования документации на основе единого источника информации.

Создаю текстовый документ со специальными метками и с помощью AsciiDoc, преобразую его в DocBook, а затем с помощью Apache FOP - в набор документов формата HTML,PDF,CHM.

Пример фрагмента исходного текста:

[[spellcheck]]
== Проверка орфографии

=== Автоматическая проверка орфографии

Для автоматической проверки орфографии используется модуль проверки из <<softOpenOffice,OpenOffice>>. 
По результатам проверки Формируется ряд отчетов, например: "ОТЧЕТ ПО АВТОМАТИЧЕСКОЙ ПРОВЕРКЕ ОРФОГРАФИИ ИСХОДНЫХ ФАЙЛОВ", "ОТЧЕТ ПО АВТОМАТИЧЕСКОЙ ПРОВЕРКЕ ОРФОГРАФИИ СЛОВАРЯ".

[NOTE]
Для использования автоматической проверки обязательно наличие установленного на компьютере <<softOpenOffice,OpenOffice>>.

[[spellcheck_orphoautosourcecodeany]]
==== Автоматическая проверка орфографии исходных файлов (любых)

Как выглядит:
На сайте: http://www.sourcelocalizer.ru/help/spellcheck.html
PDF: см. ссылку в углу экрана онлайн-справки или по ссылке http://www.sourcelocalizer.ru/help/sourcelocalizer.pdf
CHM: скачайте программу http://sourcelocalizer.ru/download :)

AsciiDoc очень удобен и прост в использовании, так как справка генерируется из системы контроля версий (svn) на сервере сборки (CI Hudson) с помощью сборочной программы (NAnt), которая еще и правит (используя регулярное выражение добавления ссылок для всех html-файлов) HTML, чтобы добавить в онлайн версию ссылки на содержание и прочее (штатные средства AsciiDoc для таких ссылок не очень подошли, см. формируемую ссылку в справке в правом верхнем угле).

Так как документацию пишу в NotePad++, то обычным ПО орфографию, особенно с учетом "переплетения" текста и тегов, проверить затруднительно.

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

Особенно проверка "любых" файлов актуальна тем, что мои файлы справки имеют расширение asciidoc. Сделал это специально, чтобы Windows генерировала готовый html через скрипты при "запуске" таких файлов.

Соответственно, наличие фразы в названии ярлыка "любых файлов" отлично подходит для моих "выдуманных" расширений файлов, а также специализированного синтаксиса. 

Очень нравится система OpenSuse открытостью своих исходных файлов локализации, на основе которых можно проверить возможности моей программы.

См. Wiki openSUSE:Перевод_документации

http://ru.opensuse.org/openSUSE:%D0%9F%D0%B5%D1%80%D0%B5%D0%B2%D0%BE%D0%B4_%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%86%D0%B8%D0%B8

Судя по всему, для сборки документации OpenSuse тоже использует Apache FOP (хотя не уверен на 100%), так как разработчики также не победили формирование текста в html в виде набора кодов (&000;) и кодировку charset=ISO-8859-1.

(Пример страницы http://doc.xboct.org/html/preface.reference.html, выберите просмотр исходного кода.), а также в одном из названий файлов есть FOP :)

В этом нет ничего страшного, хотя вообще довольно странно для FOP из UFT8 получать такие кодировки.

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

Исходная документация доступна:

http://svn.opensuse.org/svn/opensuse-doc/trunk/documents/distribution/ru/

Дальнейшую проверку провел на ревизии 11401.

О формате данной документации: 

В качестве исходных файлов используется XML, оформленный согласно DTD http://www.novell.com/documentation/osauthoring/ex_novelldtd/data/ex_novelldtd.html

формата "Open Source Documentation" http://www.novell.com/documentation/osauthoring/ex_osstyle/data/ex_osstyle.html

Фрагмент исходного файла:

http://svn.opensuse.org/svn/opensuse-doc/trunk/documents/distribution/ru/xml/opensuse_reference_intro.xml (в примере рассмотрена ревизия 11401).

<preface id="preface.reference">

 <title>Об этом руководстве</title>

 <para>

  Данное руководство даст вам общее представление о &productnamereg;. Оно

  предназначено главным образом для системных администраторов и домашних

  пользователей владеющих базовыми навыками администрирования системы.

  Изучите это руководство для ознакомления с приложениями, используемыми

  в повседневной жизни и исчерпиывающих описанием расширенной установки

  и сценариев конфигурации.

 </para>

Судя по всему, разработчики тоже используют простые текстовые редакторы без проверки орфографии.

Отличная возможность проверить функцию автоматической проверки орфографии на "любом" файле (ярлык UFT8, для ANSI отдельный ярлык в меню "Пуск"), так как изначально не закладывались возможности работы именно с NovelDoc.

Решил проверить орфографию руководства простым "броском" каталога руководства /xml на ярлык проверки орфографии "любых файлов", который создается при установке программы локализации на рабочем столе.

Отчет по результатам проверки:

1) Скачать zip-архив с html-отчетом.
2) Посмотреть PDF-версию (подрезан текст)

Фрагмент:

File: C:\test\opensusedoc\xml\art_kde_quick.xml

000032     chk:   удовлитворяющий, задачь     text:      удовлитворяющий всем профессиональным требованиям предъявляемым при выполнении задачь в

000034     chk:   предоставояет     text:      предоставояет интегрированный набор приложений для широкого круга

000069     chk:   виджет     text:       По умолчанию, виджет Рабочий стол отображает содержимое каталога

000070     chk:   помесщении     text:       <filename>~/Рабочий стол</filename>. При помесщении файла

Примечание:

Часть слов (например, виджет) отмечены не правильными, так как OpenOffice о них "не знает". Это легко исправить добавив их в словарь исключений OpenOffice. 

Данный отчет создан из текущей рабочей версии, поэтому несколько отличается оформлением от последней релизовой версии 0.9.1. 

Он был скорректирован по просьбе одного из пользователей и сейчас проходит тестирование.

Поэтому, если есть замечания/пожелания по отчету или по другим функциям программы, 

пишите (блог, сайт, ярлык "Написать письмо в службу поддержки" из каталога программы в меню "Пуск", пр.), все рассмотрю и по возможности реализую.

В дальнейшем программа локализации будет использоваться в составе скрипта сборки, 

так как она изначально предназначена для использования на серверах сборки и именно поэтому:

1. она сделана консольной;

2. в ней изначально заложено взаимодействие с системами непрерывной интеграции 

через отчеты в формате JUnit с соответствующими указаниями о правильности/замечаниях/ошибках сборки;

3. разработка ограничена версией MS FW2.0 и отсутствием внешних библиотек, 

чтобы можно было использовать на Linux из-под Wine (автоматическая проверка орфографии пока из-под Wine не работает).

Данный пост не является критикой программы OpenSuse, исходные коды которой являются замечательным примером полезности открытого ПО.

Вообще, мне всегда можно "отомстить", проверив грамматику в моей справке (пока в процессе наполнения, поэтому "мстить" явно рано), так как пока нет ярлыка "Автоматической проверки грамматики" :)

Лучший способ "мести" - сообщить, чего еще не хватает в моей программе... чтобы я ее улучшил :)