Русский Gentoo

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

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

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

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

Цели

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

Вход и выход

Реализация

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Документы 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, и копирование всего прочего из входа в выход.