Использование инструментов проверки XML developerWorks

Дополнительные инструменты для авторов, создающих статьи и руководства для публикации на developerWorks

Иен Шилдс создал несколько отличных инструментов, чтобы помочь Вам проверять, конвертировать и просматривать Ваши статьи или руководства. В статье показывается, как легко использовать эти инструменты в Microsoft® Windows® или Linux®.

Ян Шилдс, главный программист, IBM developerWorks

Ян Шилдс (Ian Shields) занимается многими Linux-проектами для developerWorks Linux zone. Он работает главным программистом IBM в Research Triangle Park, NC. Ян пришел в IBM в Канберре, Австралия, системным инженером в 1973 году и c тех пор занимался разработкой коммуникационных систем и всепроникающими вычислениями (pervasive computing) в Монреале, Канада, и RTP, NC. Защитил несколько патентов. Имеет степень магистра по чистой математике и философии от Australian National University. Также имеет степени магистра и доктора философии по компьютерным наукам от North Carolina State University.



15.12.2006 (Впервые опубликовано 15.12.2006)

Начало работы

Подготовка статьи или руководства к публикации включает следующие шаги:

  1. Скачайте авторский пакет (author package) и распакуйте файл.
  2. Создайте папку и шаблон XML для Вашей статьи или руководства.
  3. Отредактируйте шаблон XML, чтобы добавить Ваш контент, а затем проверьте XML на соответствие схеме и исправьте ошибки.
  4. Просмотрите Вашу статью или руководство в браузере, чтобы понять, как она будет выглядеть на сайте developerWorks.

Для начала прочитайте и выполните Шаги 1 и 2 из статьи "Работа авторов с XML-шаблонами developerWorks." В статье объясняется, как скачивать авторский пакет, содержащий инструменты и все необходимые файлы. В него также включены советы по написанию статей и передаче Вашего контента.

После выполнения Шагов 1 и 2 вернитесь к этой статье. Вы уже скачали авторский пакет, распаковали его на Вашей машине и создали копию шаблона с помощью инструментов new-tutorial (новое руководство) или new-article (новая статья), описанных в той статье. Теперь Вы готовы выполнить оставшиеся шаги: редактировать, проверить и просмотреть содержание, следуя данным ниже инструкциям.


При работе в Microsoft Windows

Вам потребуется:

  • Текстовый редактор или процессор, способный сохранять файлы в формате обычного текста (plain text). Хотя это и не является необходимым, Вам будет удобно пользоваться редактором, который может отображать номера строк, так как любые ошибки, обнаруженные на стадии проверки, будут сопровождаться номерами строк. Приложение Блокнот (Notepad) в Windows XP способно отображать номера строк, если Вы выберите опцию Вид (View) > Строка состояния (Status Bar). Имейте в виду, что данная опция отсутствует в более ранних версиях Блокнота для Windows.
  • Последняя на момент написания этой статьи версия Microsoft XML Parser (MSXML), содержащаяся в MSXML 4.0 Service Pack 2 (Microsoft XML Core Services). (См. раздел Ресурсы в данной статье.) Используйте ссылку msxml.msi для установки MSXML 4.0 SP2 и комплект разработчика ПО (SDK) на Ваш компьютер. Вы также можете сохранить msxml.msi на локальный диск, чтобы выполнить установку позднее.
  • Internet Explorer 6 или другой веб-браузер, например Mozilla, Firefox или Opera.

Шаг 1. Редактирование Вашего XML-файла

Зайдите в Вашу новую папку и редактируйте файл index.xml) с помощью Вашего любимого текстового редактора. Если у Вас нет иных предпочтений, Блокнота будет достаточно. Следуйте подробным инструкциям в файле шаблона index.xml. Они помогут Вам понять, что требуется делать.

Обязательно сохраняйте Ваш файл как обычный текст, если Вы используете текстовый редактор. Аналогично, если Вы вырезаете и вставляете (cut and paste) текст из файла с внутренним форматированием, например из файла Microsoft Word, либо используйте функции вставки (или специальной вставки) как текст Вашего редактора, либо обязательно сохраняйте Ваш XML-файл как обычный текст. Не изменяйте имя файла index.xml и не редактируйте HTML-файл (index.html), который Вы можете сгенерировать при помощи наших инструментов, так как Ваш редактор developerWorks будет работать с XML-версией. Сохраните любые изображения, например фотографии или скриншоты, в папке, которую Вы создали для Вашей статьи или руководства (my-article в нашем примере).

Шаг 2. Проверка XML

При редактировании Вашей статьи или руководства Вам потребуется выполнять проверку на соответствие изменений нашей схеме. Если Вы незнакомы с XML, мы рекомендуем выполнять проверку Вашего файла в ходе работы. Это поможет Вам быстрее обнаруживать ошибки.

Инструмент для проверки XML был установлен в папке Вашего проекта при создании новой статьи или руководства. Запустите скрипт dw-transform.vbs в папке Вашей статьи или руководства. В зависимости от настроек Windows, он может отображаться просто как dw-transform. Вы увидите окно как на Рисунке 1.

Рисунок 1. Проверка Вашей статьи с помощью скрипта dw-transform
Validating with the dw-transform script

Шаг 3. Исправление ошибок при проверке

Если Вы допустите ошибку в XML-коде, Вы увидите сообщение об ошибке. При использовании скрипта dw-transform, Вы увидите окно, как на Рисунке 2.

Рисунок 2. Статья с ошибками (программа проверки VB-скрипта)
An invalid article (script checker)

В данном случае мы допустили намеренную ошибку, использовав <u>Подчёркнутую фразу</u>. Так как ссылки подчёркиваются, мы не используем подчёркнутый текст для других целей в статьях и руководствах developerWorks, поэтому теги <u> и </u> не допускаются схемой. Инструмент определит местоположение первой ошибки и даст её объяснение. Объяснения генерируются MSXML parser'ом. Хотя объяснения иногда бывают загадочными, они обычно помогают определить, в чём проблема. Если в объяснении содержится Expecting (ожидается) a, b, br, ..., и далее следует список других названий тегов, Вы, возможно, неправильно напечатали название тега или попытались использовать тег, который не поддерживается схемой developerWorks (как в нашем примере). Редактор, отображающий номера строк, поможет Вам быстро находить ошибки. См. рисунок 3.

Рисунок 3. Обнаружение ошибки в Вашем XML-файле с помощью Блокнота
Locating an error in your XML with Notepad

После того, как Вы обнаружили и исправили свою ошибку, сохраните файл и снова проверьте его. Если Вы использовали dw-xmlcheck.html, нажмите на кнопку обновить (reload) в IE для повторной проверки. Если Вы использовали dw-transform.vbs, просто запустите его снова. Повторяйте процесс, пока у Вас не будет больше ошибок.

Шаг 4. Просмотр Вашей статьи или руководства

Когда Вы исправили все ошибки, Вы готовы к предварительному просмотру Вашей статьи или руководства в том виде, в каком она будет выглядеть на developerWorks. В Вашей папке должен находиться файл index.html. Откройте этот файл Вашим любимым браузером и просмотрите содержание статьи или руководства. Если Вы используете Internet Explorer с Windows XP Service Pack 2, Вы можете увидеть всплывающее окно и информационную панель, сообщающую, что Internet Explorer запретил отображение активного содержимого этого файла. Нажмите на информационную панель и выберите Allow blocked content... (Разрешить заблокированное содержимое...), чтобы просмотреть Вашу статью или руководство.

Рисунок 4. Просмотр Вашей статьи
Previewing your article

Примечания:

  • Некоторые таблицы стилей находятся на сервере, поэтому форматирование при предварительном просмотре не будет точно таким же, как при публикации на сервере редакторами developerWorks.
  • Окончательная версия руководства будет состоять из нескольких отдельных страниц, а при предварительном просмотре руководство будет отображаться как одна страница. На этой отдельной странице Вы можете увидеть, где начинается каждый раздел. Однако, перекрёстные ссылки в левой области навигации и теле руководства не работают при предварительном просмотре. Сотрудники developerWorks внесут исправления в разбивку на страницы и ссылки.

Следующие шаги

Поздравляем! Вы отредактировали, проверили и просмотрели Вашу статью или руководство. Теперь вернитесь к статье "Работа авторов с XML-шаблонами developerWorks" и просмотрите советы по окончанию работы и передаче контента редактору developerWorks.


При работе в Linux или другой операционной системе

Вам потребуется:

  • Текстовый редактор или процессор, способный сохранять файлы в формате обычного текста (plain text). Хотя это и не является необходимым, Вам будет удобно пользоваться редактором, который может отображать номера строк, так как любые ошибки, обнаруженные на стадии проверки, будут сопровождаться номерами строк. Многие редакторы под Linux или UNIX® (включая vi и emacs) способны отображать номера строк, либо всегда, либо в качестве пользовательской опции.
  • Java runtime или пакет разработки программ на Java (Java development kit), версии 1.4 или выше. Мы рекомендуем использовать пакет IBM Runtime Environment для Java 2 (JRE), так как в него включены необходимые функции Xalan и Xerces, и его можно установить вместе с другими реализациями Java. Ссылки см. в разделе Ресурсы этой статьи. Если Вы используете другую реализацию Java runtime или developer kit, Вам может также потребоваться пакет Apache Xalan версии 2.6 (включающий требуемые функции Xerces), если он не входит в Вашу версию Java. Вам может также потребоваться изменить скрипт developerworks/tools/dwxmlxslt.sh или установить переменную окружения CLASSPATH.
  • Графический браузер, например Mozilla, Firefox или Opera.

Шаг 1. Редактирование Вашего XML-файла

Зайдите в Ваш новый каталог и редактируйте Ваш XML-файл с помощью Вашего любимого текстового редактора. Следуйте подробным инструкциям в файле index.xml. Обязательно сохраняйте Ваш файл как обычный текст, если Вы используете текстовый редактор. Не изменяйте имя файла index.xml. Сохраните любые изображения, например фотографии или скриншоты, в каталоге, который Вы создали для Вашей статьи или руководства (my-tutorial в нашем примере).

Шаг 2. Проверка XML

При редактировании Вашей статьи или руководства Вам потребуется выполнять проверку на соответствие изменений нашей схеме. Если Вы не знакомы с XML, мы рекомендуем выполнять проверку Вашего файла в ходе работы. Это поможет Вам быстрее обнаруживать ошибки.

Инструмент для проверки XML был установлен в каталоге Вашего проекта при создании новой статьи или руководства. Запустите скрипт dw-transform.sh в Вашем каталоге. (Если у Вас работает среда KDE или GNOME, Вы можете запустить скрипт при помощи графического файлового менеджера, например Nautilus или Konqueror; иначе, запустите скрипт в окне терминала.)

Если всё в порядке, через несколько секунд Вы должны увидеть окно, как на Рисунке 5.

Рисунок 5. Проверка Вашего руководства с помощью скрипта dw-transform
Validating with the dw-transform shell script

Шаг 3. Исправление ошибок при проверке

Если Вы допустите ошибку в XML-коде, Вы увидите сообщение об ошибке как на Рисунке 6.

Рисунок 6. Руководство с ошибками (программа проверки скрипта командного процессора)
An invalid tutorial (shell script checker)

В данном случае мы допустили намеренную ошибку, использовав <u>Ошибку подчёркивания</u>. Так как ссылки подчёркиваются, мы не используем подчёркнутый текст для других целей в статьях и руководствах developerWorks, поэтому теги <u> и </u> не допускаются схемой. Инструмент определит местоположение первой ошибки и даст её объяснение. Объяснения генерируются Java parser'ом. Хотя объяснения иногда бывают загадочными, они обычно помогают определить, в чём проблема. Если в объяснении содержится One of (один из) '{"" , и далее следует список других названий тегов, Вы, возможно, неправильно напечатали название тега или попытались использовать тег, который не поддерживается схемой developerWorks (как в нашем примере). Редактор, отображающий номера строк, поможет Вам быстро находить ошибки. См. рисунок 7.

Рисунок 7. Обнаружение ошибки в Вашем руководстве при помощи редактора gedit
Locating an error in your tutorial with gedit

После того, как Вы обнаружили и исправили свою ошибку, сохраните файл и снова запустите скрипт dw-transform.sh, Чтобы вновь проверить Ваш файл. Повторяйте процесс, пока у Вас не будет больше ошибок.

Примечания:

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

Шаг 4. Просмотр Вашей статьи или руководства

Когда Вы исправили все ошибки, Вы готовы к предварительному просмотру Вашей статьи или руководства в том виде, в каком она (оно) будет выглядеть на developerWorks. В Вашем каталоге должен находиться файл index.html. Откройте этот файл Вашим любимым браузером и просмотрите содержание статьи или руководства.

Рисунок 8. Просмотр Вашего руководства
Previewing your tutorial

Примечания:

  • Некоторые таблицы стилей находятся на сервере, поэтому форматирование при предварительном просмотре не будет точно таким же, как при публикации на сервере редакторами developerWorks.
  • Вы можете использовать левую область навигации для навигации между разделами Вашего руководства и внутри них, так как инструмент конвертирования для Linux генерирует несколько html-страниц, похожих на те, которые будут в окончательной версии.

Следующие шаги

Поздравляем! Вы отредактировали, проверили и просмотрели Вашу статью или руководство. Теперь вернитесь к статье "Работа авторов с XML-шаблонами developerWorks" и просмотрите советы по окончанию работы и передаче контента редактору developerWorks.

Ресурсы

Научиться

Получить продукты и технологии

  • Microsoft XML Parser (MSXML):Чтобы использовать скрипт dw-transform.vbs для конвертирования Вашей статьи или руководства, Вам понадобится последняя версия MSXML parser. Вам нужен файл msxml.ms.i.
  • IBM Developer Kit для Java, Версия 1.4.2: Чтобы использовать скрипт dw-transform.sh в Linux для конвертирования Вашей статьи или руководства, Вам понадобится IBM Developer Kit для Java, Версия 1.4.2 или более поздняя.
  • Apache Xalan: Если Вы используете инструменты для Linux (dw-transform.sh) и не используете IBM Developer Kit для Java, Вам может потребоваться Apache Xalan.
  • Пробные версии ПО IBM для скачивания: Создайте Ваш следующий проект с помощью пробного ПО IBM, доступного на сайте developerWorks.

Обсудить

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=XML
ArticleID=183832
ArticleTitle=Использование инструментов проверки XML developerWorks
publish-date=12152006