Спецификация требований к TidyGuide для разработки

Автор — Алексей Чумаков, 2006-04-30

Назначение и порядок использования

TidyGuide должен стать cредством внутреннего оформления (форматирования) документов GuideXML, предназначенным для автоматического преобразования входного GuideXML-документа в выходной, соответствующий требованиям внутреннего оформления формата GuideXML.

Цели

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

Основные режимы использования

запуск вручную по команде пользователя (например, xsltproc)
в пакетной обработке на сервере (например, при автоматической публикации)

Вход и выход

На вход подается документ GuideXML (guide, book, section, metadoc)
На выходе формируется правильно оформленный GuideXML-документ
Сообщения об ошибках не порождаются

Реализация

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

Входные файлы

Структура файла: корректный (well-formed) XML-документ.

Словари данных (DTD):

www.gentoo.org/dtd/guide.dtd (формат руководства)
www.gentoo.org/dtd/book.dtd (формат книги, включая отдельную главу!)
www.gentoo.org/dtd/metadoc.dtd (индекс документов)

Кодировка — обычно UTF-8 (допускается любая кодировка)

Комментарии (необязательны):

отметка CVS
спец. комментарий переводчика
другие комментарии по тексту

Файлы могут содержать дополнительные элементы (при дальнейшем развитии DTD)

Особые случаи

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

Неизвестные теги / атрибуты / сущности обрабатываются, не порождая ошибок:

Текст и комментарии — без изменения разметки (с сохранением пробелов)
Теги и атрибуты — оформляются «по умолчанию» (всегда единообразно; пробелы в содержимом сохраняются на случай pre)

Обрезанный/дефектный документ — обрабатывается до места появления ошибки, далее копируется без обработки (вариант: копируется полностью без обработки)
Текстовый/двоичный файл не XML — копируется полностью без обработки

При затруднениях в реализации требования корректной обработки обрезанного, дефектного или не-XML документа могут быть сняты или реализованы другими (внешними) средствами.

Преобразования

Структура файла XML: сохраняется без изменений (любые ошибки xml-lint входного файла должны повторяться в выходном файле, а новые — не порождаться)

Соответствие словарю данных: без изменений

Кодировка — UTF8 (другая — преобразуется)

Пробелы (включая переводы строк):

для известных тегов, атрибутов, их содержимого — соответствуют xmlguide.
для неизвестных тегов — оформление по умолчанию как для <pre>
длина строки соответствует требованиям xmlguide (короткие строки объединены)
знак перевода строки в соответствии с ОС (в *nix — CR, в Windows — CR+LF)
признак кодировки Unicode в начале файла удаляется

Кавычки в атрибутах, регистр тегов и т.п. — приведены к единому виду

Комментарии — начинаются и заканчиваются на отдельной строке

отметка CVS — не разделена на несколько строк
другие комментарии — перенесены без изменений

Все остальное — без изменений

Выходные файлы

Документы GuideXML, соответствующие требованиям

Входной документ, полностью соответствующий требованиям (xmlguide и DTD), должен преобразовываться в такой же выходной документ, с учетом дополнительных требований:

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

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

Выходной документ, поданный на вход, должен всегда приводить к в точности одинаковому вторичному выходному документу.

Документы GuideXML, не соответствующие xmlguide

Документ, не соответствующий требованиям оформления, но соответствующий DTD, должен превращаться в документ, полностью соответствующий требованиям оформления.

Документы, не соответствующие DTD

Корректный (well-formed) документ, не соответствующий DTD (содержащий дополнительные элементы, или элементы в непредусмотренном месте, или с отсутствием обязательных элементов) превращается в документ, соответствующий требованиям оформления в части, соответствующей DTD или оформлению «по умолчанию».

Некорректные XML-документы

Некорректный (ill-formed) XML документ, о котором известно, что это XML-документ, выводится полностью без изменений (желательно), или без изменений, начиная с места первой ошибки (допустимо).

Текстовые (не XML) или двоичные файлы

Такие документы должны выводиться в точном соответствии с исходными.

Тесты

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

Тестирование может проводиться в автоматическом режиме.

Для тестирования документов, соответствующих требованиям, будет использоваться полная выборка репозитория Gentoo для различных языков, а также специально сгенерированные файлы, соответствующие DTD.

Тестирование будет выполняться на нескольких программных платформах (внимание! документ, созданный под Linux и под Windows, должны отличаться в части перевода строк.)

Ссылки и мысли

http://www.dpawson.co.uk/xsl/sect4/N10301.html — обсуждение форматирования и представления XML-документов с примерами

http://www.xmlhack.ru — русский сайт разработчиков XML с форумом

http://www.exslt.org/ — расширения XSLT

http://www.kitebird.com/software/ — сценарий Perl/Ruby для форматирования произвольного XML по шаблону

В заключение — упрощение задачи

Если в лоб не получится, можно (пока) упростить решение:

Требование обработки без изменений файлов, не являющихся корректным XML, если не реализуемо в XSLT, можно реализовать алгоритмически сценарием так:

xmllint вход DTD
если порядок,
	xsltproc вход >выход
иначе
	cp вход выход

Так на наш xslt попадет только файл нужной структуры. Теперь (зная структуру) мы можем взять за основу нашего XSLT готовый guide.xsl/book.xsl с gentoo.org, которые генерируют HTML, и сделать из них генератор GuideXML.

Можно и с незнакомыми тегами, тогда xmllint — только проверка на wellformedness, и копирование всего прочего из входа в выход.

Русский Gentoo