Работа авторов с XML-шаблонами developerWorks

Опции документа Опции документа, требующие включения JavaScript, не отображаются Исходные тексты примера Выскажите мнение об этой странице Помогите нам улучшить содержание

Уровень сложности: простой

Сотрудники редакции, developerWorks, IBM　

10.02.2005
Обновлено 15.07.2008

Приветствуем вас, авторы! В данной статье объясняется, как готовить технические статьи и руководства к публикации на developerWorks. Это очень просто. Вы закачиваете наш XML-шаблон для статей или руководств, заполняете шаблон при помощи любого проверяющего XML-редактора или предпочитаемого вами текстового редактора, работающего под Microsoft® Windows® или Linux®, проверяете, соответствует ли он структуре тегов, указанных в схеме developerWorks, и предварительно просматриваете вашу статью или руководство. Здесь также затрагиваются правила составления материалов и передачи их сотрудникам developerWorks.

Предпочитаете пользоваться шаблонами Word или Writer вместо XML? Если вам удобнее работать в программах Microsoft Word или OpenOffice.org Writer, то для них мы также предоставляем шаблоны. Работа с ним описана в статье "Работа авторов статей developerWorks с шаблонами Word и Writer."

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

Редакторы developerWorks будут рады сотрудничать с вами в публикации ваших материалов. Пожалуйста, обязательно сначала представьте редактору вашу идею и получите его/её одобрение, прежде чем продолжать работать с данными инструкциями. Если вы ещё не сделали этого, используйте нашу форму передачи материалов, чтобы передать вашу идею.

Статьи и руководства публикуются на сайте developerWorks в формате HTML, но пишутся в формате XML (расширяемый язык разметки). Перед публикацией XML-источник каждой статьи и руководства проверяется на правильность разметки, как указано в схеме developerWorks, а затем конвертируется для публикации в HTML с помощью таблицы стилей XSLT (расширяемый язык таблиц стилей). Такое разделение содержания статьи и деталей представления помогает нам использовать автоматизированные процессы для управления нашим большим сайтом.

Предлагаемые нами подходы к авторским разработкам не требуют специальных навыков. Если вы уже знакомы с XML или HTML, вам будет легко использовать наши шаблоны для статей и руководств. Если нет, вы можете ознакомиться с XML, прочитав cоветы по заполнению шаблонов ниже в данной инструкции, а также посетив страницу Новичкам об XML в разделе XML developerWorks Россия.

В начало

Статья или учебное пособие?

Если вы уже посещали сайт developerWorks, вы знаете, что большую часть контента developerWorks составляют статьи и пособия. Их формат и цели различны. Редактор developerWorks Россия может помочь вам решить, какой формат лучше подходит для вашего материала.

Руководства

• Руководства преследуют образовательные цели; они обучают. В них не только перечисляются шаги, но и объясняется, почему выполняется тот или иной шаг, и как он соотносится с главной целью. В руководствах прямо формулируются образовательные цели, а также указывается время выполнения (обычно около двух часов). После ознакомления с руководством читатель должен быть в состоянии повторить изученное задание самостоятельно.
• В руководствах могут объясняться общие идеи, а также способы выполнения конкретных задач. Многие руководства содержат и то и другое и поощряют читателей выполнять эти задачи во время чтения. Для облегчения понимания в руководства часто включаются примеры программ и советы по настройке пользовательской среды. Содержание руководств часто представляется в виде отдельных и легко выполнимых задач.
• Для получения доступа к руководствам требуется регистрация.
• В распечатанном виде руководства занимают от 20 до 30 страниц. И, поскольку на выполнение задачи может потребоваться несколько часов, многие читатели распечатывают PDF-файл руководства во время или после выполнения задачи для справочных целей.
• Руководство может состоять из одной части или быть частью серии из нескольких частей.

Статьи

• Как и руководства, статьи преследуют образовательные цели, хотя не так явно, как руководства. В статьях не объясняются образовательные цели и не указывается время выполнения.
• Кроме обучения читателей выполнению конкретных операций, статьи часто знакомят с новыми понятиями, архитектурами или функциями продуктов. Цель таких статей - повысить уровень осведомлённости читателей и стимулировать их интерес к дальнейшему изучению предмета (возможно, чтению других руководств developerWorks!). Другие статьи написаны в более дискуссионном ключе, то есть автор рассказывает о своём уникальном подходе, перспективе или опыте. И, наконец, в статьях третьего типа подробно описываются новые продукты или технологии. Для этого интервьюируется эксперт или делается обзор современной литературы по данному вопросу.
• Для получения доступа к статьям не требуется регистрация.
• В распечатанном виде статьи в среднем занимают 10 или менее страниц. Читатели обычно работают со статьями в онлайне.
• Как и руководство, статья может состоять из одной части или быть частью серии из нескольких частей.

В начало

Основные шаги

Для создания статьи или руководства выполните следующие шаги:

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

В начало

Шаг 1. Загрузка авторского пакета

Загрузите файл author-package.zip и сохраните его в подходящем месте (например, C:\ в Windows или в каталоге home в Linux). Распакуйте файл, чтобы разместить все файлы в нужном месте.

Папка developerworks не обязательно должна располагаться в корневом каталоге или на диске, на котором установлена Windows (C:\). Однако расположение файлов внутри папки developerworks и её подпапок существенно, поэтому сохраняйте структуру папки developerworks и имена файлов как есть.

Если вы работаете с Linux, то вам следует скачать пакет разработчика на Java от IBM (IBM Developer Kit for Java, ссылка приведена в разделе Ресурсы) и установить его в каталог /opt/ibm (при условии tarball-архива). Средства проверки, описанные в статье “Использование средств проверки XML-формата статей developerWorks”, работают только с теми версиями Java, которые включают библиотеку Xalan (Java 5.0 включает в себя Xalan 2.7).

После того, как вы распакуете файл, вы увидите папку (или каталог) developerworks, содержащую следующие подпапки:

• readme – содержит файл readme.html. В нем содержится ссылка на статью, которую вы читаете в настоящий момент.
• schema - содержит файлы схемы. Главный файл схемы называется dw-document-5.10.xsd. (5.10 – это версия схемы developerWorks на момент написания этой статьи.)
• tools - содержит два шаблона (template-dw-article-5.10.xml и template-dw-tutorial-5.10.xml), а также несколько простых инструментов, которые помогут вам в создании и проверке новой статьи. Подкаталог java содержит исходные коды Java™-программ, которые используются с инструментом проверки и конвертирования для Linux, на случай, если вы захотите их изменить или перекомпилировать.
• web – содержит файлы изображений и JavaScript для предварительного просмотра статьи или руководства.
• xsl - содержит главный файл таблицы стилей dw-document-html-5.10.xsl и несколько вспомогательных таблиц стилей.

Файлы и инструменты, включённые в авторский пакет, предназначены для использования под Linux или Windows. Если вам требуется помощь в редактировании шаблонов для их использования с операционной системой, отличной от Windows или Linux, свяжитесь с редактором developerWorks Россия.

В начало

Информация о версии

Прежде чем перейти к Шагу 2, рассмотрим, что изменилось в этой версии.

С 21 марта 2008 г. авторы могут работать со схемами и таблицами стилей XSL версии 5.10. В них произошли некоторые внутренние изменения, направленные на использование современных Web-технологий для поддержки социальных тегов и управления данными. Внешние изменения минимальны и в основном заключаются в следующих модификациях шаблонов статей и руководств:

• Поддержка разных вариантов форматирования (обычный или жирный шрифт, курсив) в пределах одной строки листинга без принудительного перевода строки.
• Многострочное выделение текста в листингах (жирный шрифт или курсив) с помощью всего одной пары тегов.
• Элементы “Component”, “Grid”, “Unicode”, “Wireless” и “Workplace” больше не могут использоваться в разделе содержимого статьи или руководства.

Содержимое архива author-package.zip и данная статья соответствуют схемам и шаблонам версии 5.10. Если вы используете более ранние версии авторского пакета, вам следует скачать author-package.zip версии 5.10, воспользовавшись ссылкой в разделе Загрузка.

Для проверки и конвертации статей и руководств используются одни и те же файлы главной схемы (файл xsd) и главной таблицы стилей (файл xsl).

• Главная схема: dw-document-5.10.xsd
• Главная таблица стилей: dw-document-html-5.10.xsl

В начало

Шаг 2. Создание нового шаблона

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

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

В папке developerworks дважды щёлкните new-article.vbs, чтобы создать статью, или new-tutorial.vbs, чтобы создать руководство. В качестве имени папки вы можете выбрать любое допустимое имя. По умолчанию предлагаются имена my-article и my-tutorial.

После нажатия OK, вы увидите новую папку в папке developerworks. Возможно, вам придётся обновить представление (View > Refresh), чтобы увидеть её. Эта новая папка содержит шаблон вашей статьи или руководства (index.xml), а также скрипт проверки и трансформации (dw-transform.vbs).

При работе с Linux

Используйте сценарий (скрипт) командного процессора new-article.sh или new-tutorial.sh в каталоге developerworks. (В среде KDE или GNOME вы можете запустить скрипты при помощи графического файлового менеджера, например Nautilus или Konqueror; иначе запустите скрипт в окне терминала.) Вы увидите диалоговое окно, в котором вы можете ввести имя вашего нового проекта. Вы можете выбрать любое допустимое имя. По умолчанию предлагаются имена my-article и my-tutorial.

После того как вы щёлкнете OK (или нажмёте Enter, вы увидите новый каталог в каталоге developerworks. Этот новый каталог содержит шаблон вашей статьи или руководства (index.xml), а также скрипт проверки и преобразования (dw-transform.sh).

Если вы работаете в графической среде, то вам понадобится пакет zenity, gdialog bkb kdialog для рабочего стола GNOME или KDE. В противном случае достаточно будет пакета dialog.

В начало

Шаг 3. Редактирование и проверка вашего XML-кода

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

Использование проверяющего XML-редактора

Использование проверяющего XML-редактора для редактирования и проверки вашего XML-кода помогает выявлять любые ошибки непосредственно в ходе работы. Сегодня на рынке имеется множество коммерческих XML-редакторов как для Windows, так и для Linux. Приведём три примера: ПО Rational® Web Developer для WebSphere®, <oXygen/> и Altova XMLSpy (см. Ресурсы, чтобы скачать ПО и документацию). У всех трёх имеются бесплатные пробные версии, и мы рекомендуем прочитать прилагающиеся к продуктам инструкции, чтобы научиться их использовать. Все необходимые файлы поддержки, которые могут вам потребоваться для работы с этими продуктами или другими коммерческими XML-редакторами для разработки ваших статей или руководств, находятся в файле author-package.zip developerWorks.

Имеется также ряд бесплатных XML-редакторов. Помимо вышеупомянутой коммерческой версии XMLSpy, Altova представила бесплатную версию XMLSpy Home Edition. Кроме того, для платформы Eclipse имеются плагины, которые вы можете использовать для подготовки XML-документов. См. Ресурсы.

При работе с проверяющим XML-редактором или средой разработки имейте в виду следующее:

• В шаблонах ссылки на файлы схемы и таблицы стилей являются относительными, то есть указывается только путь к папке вашей статьи или руководства. Вам, возможно, потребуется изменить ссылки (..\schema\5.10\dw-document-5.10.xsd и ..\xsl\5.10\dw-document-html-5.10.xsl) на абсолютные ссылки, например C:\developerworks\schema\5.10\dw-document-5.10.xsd. В некоторых редакторах вам, возможно, придётся указать местонахождение этих файлов другими способами конфигурации.
• Если вы редактируете ваше руководство или статью в XML-редакторе и ни одно изображение не открывается, вполне вероятно, что редактор создал HTML-файл в папке, предназначенной для временного хранения файлов. В этом случае вам придётся сохранить сгенерированный HTML-файл в папке вашей статьи (в нашем примере my-article), и открыть его либо в графическом XML-редакторе, либо с помощью браузера.

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

Если вы не можете найти проверяющий XML-редактор по вашему вкусу, или предпочитаете не тратить время на ознакомление с ним, вы можете использовать ваш любимый текстовый редактор для редактирования XML-шаблона, а затем прибегнуть к инструментам из авторского пакета (dw-transform.vbs для Windows или dw-transform.sh для Linux) для проверки XML-кода и трансформации его в HTML. Затем вы можете просмотреть HTML в браузере. Подробности использования этих простых инструментов указаны в сопутствующей статье "Использование средств проверки XML-формата статей developerWorks".

В начало

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

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

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

Если вы используете текстовый редактор и скрипты developerWorks, результирующий HTML-файл будет создан в папке вашей статьи или руководства. Откройте index.html в браузере. Более подробные инструкции по использованию этих скриптов находятся по адресу Использование средств проверки XML-формата статей developerWorks".

В начало

Советы по заполнению шаблонов

Новичкам об XML Как и во всех XML-документах, в XML-шаблонах из авторского пакета выполняются следующие правила: XML-теги (строки между < и >) пишутся в нижнем регистре. XML-теги обычно образуют пару: начальный тег и соответствующий конечный тег. Например, <title> и </title> являются начальным и конечным тегами для заголовка вашей статьи или руководства. Ваш текст размещается между тегами, например <title>Ваш текст</title>. Исключениями из правила парных тегов являются такие теги, как line break (разрыв строки) (<br />) или image tag (тег изображения) (<img />), здесь один тег служит и как начальный, и как конечный; в этом случае, тег заканчивается />. Строки комментариев окружаются <!-- и -->.

XML-шаблоны являются наилучшим источником исчерпывающих сведений по разработке ваших статей или руководств. Пространные комментарии в шаблонах (template-dw-article-5.10.xml и template-dw-tutorial-5.10.xml в папке tools) подробно обрисуют вам все аспекты кодирования вашей статьи или руководства. Вы можете также ознакомиться с исходным XML-кодом данной статьи (index.xml в папке readme). Вот ещё несколько советов, которые могут оказаться полезными:

• Работаете в Microsoft Word или OpenOffice Writer?

  Вы можете использовать шаблоны Word и Writer вместо XML. Подробные инструкции приведены в статье "Работа авторов статей developerWorks с шаблонами Word и Writer".

  Кроме этого, вы можете вырезать и вставлять текст (cut and paste) из файлов других форматов в XML-шаблон. Если вы вырезаете и вставляете текст из файла с внутренним форматированием, например из файла Microsoft Word, используйте функции вашего редактора "Вставить" (paste) (или "Специальная вставка" (paste special)) в виде текста (as text), либо сохраните файл как TXT-файл, и лишь после этого вырезайте и вставляйте текст. Не вырезайте и вставляйте текст непосредственно из форматированного файла, например из файла Word. Если ваш файл (Word или Writer) содержит изображения, то можете не заботиться об их извлечении, просто перешлите файл редактору developerWorks Россия, и наши дизайнеры вырежут и обработают необходимые рисунки. И наконец, если документ находится в режиме отслеживания изменений (Track Changes), то обязательно выключите эту функцию перед копированием текста в шаблон XML. В противном случае в XML вставится некая каша из отредактированного и удаленного текста.

• Не забывайте использовать закрывающие теги. Например, для каждого тега абзаца (<p>) требуется конечный тег (</p>). Кроме того, для пустых элементов, например для тега разрыва строки (<br />) и для тега изображения (<img />) требуется конечная наклонная черта (slash).
  
  
• Не используйте следующие теги: span, code font, CDATA, а также font classes.
  
  
• При включении в текст статьи или руководства листингов программ:
  
  
• Ограничивайте длину строки программы 90 символами, ВКЛЮЧАЯ пробелы.
  
  
• Ограничивайте длину листинга 100 строками, ВКЛЮЧАЯ пустые строки.

  Если листинг содержит более 100 строк, разбивайте его на несколько частей или выделяйте наиболее важные фрагменты. Полную версию можно выложить в разделе Загрузка в конце статьи или руководства.

• Избегайте жёсткого кодирования пробелов или знаков табуляции в конце строки кода программы.
  
  
• Избегайте использования знаков табуляции в начале строки кода программы. Если необходимо сделать отступ, используйте пробелы.
  
  
• Не используйте теги CDATA. Если необходимо отобразить теги XML, например, угловые скобки, внутри листинга, то используйте специальные символы < и > (полный перечень таких символов приведен в таблице 1).
  
  
• Не используйте цвета. Если необходимо выделить часть кода программы, используйте жирный шрифт (<b> and </b>).
  
  
• Если требуется пример кода программы для загрузки, заархивируйте его и отошлите zip-файл вашему редактору отдельно.
  
  
• Все графические файлы, включая скриншоты, должны быть в формате JPG или GIF и не должны превышать 572 или 500 пикселов в ширину (для статей и руководств соответственно). Отошлите все графические файлы вашему редактору. Обратитесь к статье " Иллюстрирование вашей статьи или руководства для developerWorks" чтобы узнать подробнее, как создавать и эффективно работать с графическими файлами.
  
  
• Специальные символы кодируются, как указано ниже:
  
  
  
  

  Таблица 1. Специальные символы

  Символ	Кодирование в XML
  Амперсанд (&)	& (Всегда кодируйте амперсанды как & -- даже в URL.)
  Апостроф (')	'
  Знак больше (>)	>
  Знак меньше (<)	&lt;
  m-dash (—)	<mdash />
  Кавычки (")	&quot;
  Зарегистрированная торговая марка (®)	<reg/> (Авторы могут, но не обязаны, вставлять символ товарного знака; редколлегия developerWorks позаботится об этом.)
  Торговая марка(™)	<trade/> (Авторы могут, но не обязаны, вставлять символ товарного знака; редколлегия developerWorks позаботится об этом.)

  
  
  
  

  Например, чтобы включить угловые скобки в разделе кода:

  <TABLE border="0" width="100%">

  
  

  в XML-шаблон следует внести следующий код:
  
  <TABLE border="0" width="100%">

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

В начало

Правила выделения текста

Не уверены, где нужны теги <code type="inline">, а где нет? Вы используете курсив или кавычки в заглавии книги? Когда нужно использовать жирный шрифт, а когда вообще ничего не выделять? В таблице 2 даны правила выделения текста, рекомендуемые для статей developerWorks.

Образцы кода программ

В начало

Передача вашей статьи или руководства developerWorks

Когда вы закончите ваш труд, можно отправлять его редактору developerWorks. Отправьте по электронной почте XML-файл вашей статьи или руководства (вместе с прилагающимися изображениями или образцами кода программ) вашему редактору. Подробные рекомендации и советы по созданию и передаче графических файлов для вашей статьи см. по адресу " Иллюстрирование вашей статьи или руководства для developerWorks: Советы для авторов по графическому оформлению."

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

В начало

Загрузка

	Информация о методах загрузки

Ресурсы

• Оригинал статьи: Authoring with the developerWorks XML templates (EN).
  
  
• "Использование инструментов проверки XML developerWorks" (developerWorks, февраль 2006 г.): если вы предпочитаете использовать текстовый редактор для редактирования XML-шаблона, вы можете использовать инструменты, поставляемые с авторским пакетом для проверки вашего XML-кода и просмотра контента.
  
  
• "Иллюстрирование вашей статьи или руководства для developerWorks: Советы для авторов по графическому оформлению." (developerWorks, январь 2006 г): получите подробные рекомендации и советы по созданию и передаче графических файлов для вашей статьи или руководства.(EN)
  
  
• Рекомендации для авторов developerWorks и редакционная политика: узнайте больше о нашей редакционной политике и ознакомьтесь со списком пожеланий к содержанию каждого редактора developerWorks.(EN)
  
  

• Microsoft XML Parser (MSXML): чтобы использовать скрипт dw-transform.vbs для конвертирования вашей статьи или руководства, вам понадобится последняя версия синтаксического анализатора MSXML. Вам нужен файл msxml.ms.i.(EN)
  
  
• IBM Developer Kit для Java, Версия 1.4.2: чтобы использовать скрипт dw-transform.sh в Linux для конвертирования вашей статьи или руководства, вам понадобится IBM Developer Kit для Java, Версия 1.4.2 или более поздняя.(EN)
  
  
• Rational® ПО Web Developer для WebSphere® Версия 6.0: скачайте пробную версию непосредственно с сайта developerWorks.(EN)
  
  
• Пробные версии ПО IBM для скачивания: используйте в вашем следующем проекте ознакомительное ПО IBM, которое можно скачать с сайта developerWorks.(EN)
  
  
• XML-редакторы: внимательно прочитайте список бесплатных XML-редакторов, который ведёт Ларс Мариус Гарсхол.(EN)
  
  
• <oXygen/> XML-редактор и XSLT-отладчик (для разных платформ) и Altova XMLSPY (для Windows): ознакомьтесь и скачайте пробные версии других коммерческих XML-продуктов.(EN)
  
  
• " XML-разработка при помощи Eclipse" (developerWorks, апрель 2003 г.): создавайте XML-документы с помощью платформы Eclipse и таких плагинов, как Bocaloco Software XMLBuddy.(EN)
  
  

• Форма передачи контента: передайте идею статьи или руководства в developerWorks, и вступите в контакт с редактором developerWorks.(EN)

Об авторе

		Данный контент доводится до Вашего сведения сотрудниками редакции developerWorks.

Выскажите мнение об этой странице

Пожалуйста, найдите минутку и заполните форму, чтобы повысить уровень сервиса. Помогла ли данная информация достичь Вашей цели? Да Нет Не знаю   Пожалуйста, напишите комментарий, чтобы мы могли улучшить данную страницу:   Насколько полезна эта информация? (1 = Бесполезна, 5 = Очень полезна) 1 2 3 4 5

Поделиться этой статьей: забобрить сохранить в memori

В начало