 | Уровень сложности: простой Сотрудники редакции, developerWorks, IBM
10.02.2005
Обновлено 14.02.2006 Приветствуем Вас, авторы! В данной статье объясняется, как готовить технические статьи и руководства к публикации
на developerWorks. Это очень просто. Вы закачиваете наш XML-шаблон для статей или руководств, заполняете шаблон при помощи
любого проверяющего XML-редактора или предпочитаемого Вами текстового редактора, работающего под
Microsoft® Windows® или Linux®, проверяете, соответствует ли он структуре тегов,
указанных в схеме developerWorks, и предварительно просматриваете Вашу статью или руководство.
Здесь также затрагиваются правила составления материалов и передачи их сотрудникам developerWorks.
Начало работы
Редакторы developerWorks стремятся к сотрудничеству
с Вами, чтобы опубликовать Ваш материалы. Пожалуйста, убедитесь, что Вы
представили редактору Вашу идею, и получили его/её одобрение,
прежде чем продолжать работать с данными инструкциями. Если Вы ещё не сделали этого,
используйте нашу
форму передачи материалов, чтобы
передать Вашу идею.
Статьи и руководства публикуются на сайте developerWorks в формате HTML,
но пишутся в формате XML (расширяемый язык разметки). Перед публикацией XML-источник каждой статьи и руководства
проверяется на правильность разметки, как указано в схеме developerWorks, а затем
конвертируется для публикации в HTML с помощью таблицы стилей XSLT (расширяемый язык таблиц стилей).
Такое разделение содержания статьи и деталей представления
помогает нам использовать автоматизированные процессы для управления нашим большим сайтом.
Предлагаемые нами подходы к авторским разработкам не требуют специальных навыков.
Если Вы уже знакомы с XML или HTML, Вы найдёте наши шаблоны для статей и руководств
лёгкими в использовании. Если нет, Вы можете ознакомиться с XML,
прочитав cоветы по заполнению шаблонов ниже в данной инструкции,
а также посетив страницу Новичкам об XML в
разделе XML developerWorks Россия.
Статья или учебное пособие?
Если Вы уже посещали сайт developerWorks, Вы знаете, что статьи и
пособия составляют большую часть контента developerWorks. Их формат и цели различны.
Редактор developerWorks Россия может помочь Вам решить, какой формат лучше подходит для Вашего материала.
Руководства
- Руководства преследуют образовательные цели; они обучают. В них не только
перечисляются шаги, а объясняется, почему выполняется тот или иной шаг, и как он соотносится с
главной целью. В руководствах доходчиво объясняются образовательные цели,
а также указывается время выполнения (обычно около двух часов). После
ознакомления с руководством читатель должен быть в состоянии повторить
изученное задание самостоятельно.
- В руководствах могут объясняться общие идеи, а также способы выполнения конкретных задач.
Многие руководства содержат и то, и другое, и они поощряют читателей выполнять эти задачи
во время чтения. Для облегчения понимания в руководства часто включаются примеры программ и советы
по настройке пользовательской среды. Содержание руководств часто представляется в виде
отдельных и легко выполнимых задач.
- Для получения доступа к руководствам требуется регистрация.
- В распечатанном виде руководства занимают от 20 до 30 страниц. А так как на выполнение
задачи может потребоваться несколько часов, многие читатели распечатывают
PDF-файл руководства во время или после выполнения задачи для справочных целей.
- Руководство может состоять из одной части или быть частью серии из нескольких частей.
Статьи
- Как и руководства, статьи преследуют образовательные цели, хотя не так явно, как руководства.
В статьях не объясняются образовательные цели и не указывается время выполнения.
- Кроме обучения читателей выполнению конкретных операций, статьи часто
знакомят с новыми понятиями, архитектурами или функциями продуктов.
Цель таких статей - повысить уровень осведомлённости читателей
и разжечь их интерес к дальнейшему изучению предмета (возможно, читая другие руководства developerWorks!).
Другие статьи написаны в более аргументативном ключе, то есть
автор рассказывает о своём уникальном подходе, перспективе или опыте.
И, наконец, в ещё одном виде статей подробно описывается новый продукт или технология.
Для этого интервьюируется эксперт или делается обзор современной литературы по данному вопросу.
- Для получения доступа к статьям не требуется регистрация.
- В распечатанном виде статьи в среднем занимают 10 или менее страниц.
Читатели обычно работают со статьями в онлайне.
- Как и руководство, статья может состоять из одной части или быть частью серии из нескольких частей.
 |
Основные шаги
Создайте статью или руководство, выполнив следующие шаги:
- Загрузите авторский пакет (author package) и распакуйте файл.
- Создайте папку и шаблон XML для Вашей статьи или руководства.
- Отредактируйте шаблон XML, чтобы добавить Ваш материал,
а затем проверьте XML на соответствие схеме и исправьте ошибки.
- Просмотрите Вашу статью или руководство в браузере,
чтобы понять, как она будет выглядеть на сайте developerWorks.
Шаг 1. Загрузка авторского пакета
Загрузите файл author-package.zip
и сохраните его в подходящем месте (например,
C:\ в Windows или в каталоге home в Linux).
Распакуйте файл, чтобы разместить все файлы в нужном месте.
Папка developerworks не обязательно должна располагаться в
корневом каталоге или на диске, на котором установлена Windows (C:\).
Однако расположение файлов внутри папки developerworks и её
подпапок имеет важное значение, поэтому сохраняйте структуру папки
developerworks и имена файлов как есть.
После того, как Вы распакуете файл, Вы увидите папку (или каталог) developerworks,
содержащую следующие подпапки:
- i -- содержит изображения, необходимые для просмотра Вашей статьи или руководства.
- js -- содержит java-скрипт, необходимый для просмотра Вашей статьи или руководства.
- readme -- содержит копию данной статьи (index.html),
а также сопутствующую статью по использованию альтернативных продуктов (tools.html).
Также прилагается XML-исходник и для той, и для другой статьи (index.xml и tools.xml).
- schema -- содержит файлы схемы. Главный файл схемы
называется dw-document-n.n.xsd. (n.n - это уровень
схемы developerWorks. 5.3 - уровень схемы на момент написания этой статьи.)
- xsl -- содержит первичный файл таблицы стилей
dw-document-html-n.n.xsl и несколько вторичных таблиц стилей.
- tools -- содержит два шаблона
(template-dw-article-5.3.xml и
template-dw-tutorial-5.3.xml), а также несколько простых инструментов,
которые помогут вам в создании и проверке новой статьи. Подпапка java содержит
исходные коды Java™-программ, которые используются
с инструментом проверки и конвертирования для Linux, на случай, если Вы захотите
их изменить или перекомпилировать.
Файлы и инструменты, включённые в авторский пакет, предназначены для использования под Linux или Windows.
Если Вам требуется помощь в редактировании шаблонов для их использования с операционной системой,
отличной от Windows или Linux, пожалуйста, свяжитесь с редактором developerWorks Россия.
Информация по версии
Перед тем, как перейти к Шагу 2, давайте рассмотрим, что изменилось в этой версии. Во время написание данной статьи номер версии
схемы и таблицы стилей developerWorks - 5.3. Файл author-package.zip и данная статья соответствуют версии 5.3.
Вы должны готовить Вашу статью или руководство, используя схему и таблицу стилей версии 5.3. Если Вы используете более раннюю версию
схемы и таблицы стилей developerWorks, Вам необходимо загрузить файл author-package.zip версии 5.3.
Схема и таблицы стилей версии 5.3 были выпущены 26 января 2006, и по сравнению
с предыдущей версией в них внесены лишь минимальные изменения. И руководства, и статьи
используют одни и те же первичную схему (xsd-файл) и первичную таблицу стилей(xsl-файл):
- Первичная схема: dw-document-5.3.xsd
- Первичная таблица стилей: dw-document-html-5.3.xsl
Ниже дан список изменений, которые могут быть интересны авторам:
- Благодаря изменению внутреннего пути скорость просмотра Вашей статьи или руководства
в проверяющем XML-редакторе, например в XMLSpy, возросла.
- Если Вы пишете статью, у Вас есть возможность включить в неё информацию о торговых марках,
которая появится и в онлайновой, и в напечатанной версиях статьи.
В качестве примера смотрите информацию о торговых марках в конце данной статьи.
Пример кодирования информации о торговых марках дан в Листинге 1:
Листинг 1. Как закодировать информацию о торговых марках в Вашем XML-файле статьи
:
</docbody>
<trademarks>
<trademark>DB2, eServer, Lotus, PowerPC, Rational, Tivoli, и WebSphere
являются торговыми марками Корпорации IBM в Соединённых Штатах и/или в других странах.
</trademark>
<trademark>Linux является торговой маркой Линуса Торвальдса в Соединённых Штатах,
и/или в других странах.</trademark>
</trademarks>
<resources>
: |
Шаг 2. Создание нового шаблона
В ходе этого шага Вы создадите свою собственную копию шаблона
статьи или руководства с помощью инструмента из авторского пакета.
В результате в отдельной папке будет создан новый файл под названием index.xml.
Будет выполнена настройка правильных путей, а также настройка правильной работы шаблона
в различных операционных системах.
При работе с Microsoft Windows
В папке developerworks дважды щёлкните
new-article.vbs, чтобы создать
статью, или new-tutorial.vbs, чтобы создать
руководство. В качестве имени папки Вы можете выбрать любое допустимое имя.
По умолчанию предлагаются имена my-article и my-tutorial.
Рисунок 1.
Создание и присвоение имени новой статье в Windows
После нажатия 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.
Рисунок 2.
Создание и присвоение имени новому руководству в Linux
После того, как Вы щёлкнете OK (или нажмёте Enter),
Вы увидите новый каталог в каталоге developerworks.
Этот новый каталог содержит шаблон Вашей статьи или руководства (index.xml),
а также скрипт проверки и трансформации (dw-transform.sh).
Шаг 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.3\dw-document-5.3.xsd и
..\xsl\5.3\dw-document-html-5.3.xsl)
на абсолютные ссылки, например
C:\developerworks\schema\5.3\dw-document-5.3.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.3.xml и template-dw-tutorial-5.3.xml в папке
tools) подробно обрисуют Вам каждый аспект кодирования Вашей статьи или руководства.
Вы можете также ознакомиться с исходным XML-кодом данной статьи (index.xml в папке
readme). Вот ещё несколько советов, которые Вы можете найти полезными:
- Вы можете вырезать и вставлять текст (cut and paste) из файлов других форматов в XML-шаблон.
Если вы вырезаете и вставляете текст из файла с внутренним форматированием, например из файла Microsoft Word,
используйте функции Вашего редактора "Вставить" (paste) (или "Специальная вставка" (paste special)) в виде текста (as text),
либо сохраните файл как TXT-файл, и лишь после этого вырезайте и вставляйте текст.
Не вырезайте и вставляйте текст непосредственно из форматированного файла, например из файла Word.
- Не забывайте использовать конечные теги. Например, для каждого тега абзаца (<p>) требуется конечный тег (</p>).
Кроме того, для пустых элементов, например для тега разрыва строки (<br />) и для тега изображения (<img />)
требуется конечная наклонная черта (slash).
- Не используйте следующие теги: span tags, code font tags, а также font classes.
- При включении в текст листингов программ:
- Ограничивайте длину строки программы 70-ю символами, ВКЛЮЧАЯ пробелы.
- Избегайте жёсткого кодирования пробелов или знаков табуляции в конце строки кода программы.
- Избегайте использования знаков табуляции в начале строки кода программы. Если необходимо сделать отступ,
используйте пробелы.
- Не используйте цвет. Если необходимо выделить часть кода программы, используйте жирный шрифт
(<b> and </b>).
- Если требуется пример кода программы для загрузки, заархивируйте его
и отошлите zip-файл Вашему редактору отдельно.
- Все графические файлы, включая скриншоты, должны быть в формате JPG или GIF, и не должны превышать 572 пикселов в ширину.
Отошлите все графические файлы Вашему редактору. См. "
Иллюстрирование Вашей статьи или руководства для developerWorks" чтобы узнать подробнее,
как создавать и эффективно работать с графическими файлами.
- Специальные символы кодируются, как указано ниже:
Таблица 1. Специальные символы | Символ | Кодирование в XML |
|---|
| Амперсанд (&) | & (Всегда кодируйте амперсанды как & -- даже в URL.) | | Апостроф (') | ' | | Знак больше (>) | > | | Знак меньше (<) | < | | Кавычки (") | " | | Зарегистрированная торговая марка (®) | <reg/> (Авторы могут, но не обязаны, вставлять символ торговой марки; редколлегия developerWorks
позаботится об этом.) | | Торговая марка(™) | <trade/> (Авторы могут, но не обязаны, вставлять символ торговой марки; редколлегия developerWorks
позаботится об этом.) |
Например, чтобы включить угловые скобки в разделе кода:
<TABLE border="0" width="100%"> |
В XML-шаблон следует внести следующий код:
<TABLE border="0"
width="100%">
- И наконец, чтобы лучше видеть результаты в ходе работы (и чтобы расположить к себе Вашего редактора developerWorks),
удаляйте строки комментария из файла статьи по мере того, как Вы усваиваете тегирование.
|
Правила выделения текста
Не уверены, для чего требуется<code type="inline"> тегирование, а для чего нет?
Вы используете курсив или кавычки в заглавии книги? Когда нужно использовать жирный шрифт, а когда вообще ничего не выделять?
В таблице 2 даны правила выделения текста, рекомендуемые для статей developerWorks.
Таблица 2. Рекомендуемые выделения| Выделяемый элемент | Рекомендуемые выделения | Пример |
|---|
| "Названия статей" | Кавычки | "Названия статей" | | Названия книг | Курсив | <i>Названия книг</i> | Код C/C++ | Линейное кодирование | <code type="inline">Код C/C++</code> | Классы | Линейное кодирование | <code type="inline">Классы</code> |
| Раздел кода | <code type="section">
Образцы кода программ
</code> | Фрагменты кода (менее одной строки) в тексте | Линейное кодирование | <code type="inline">Фрагменты кода (менее одной строки) в тексте</code> | | Названия колонок или серий | Курсив | <i>Названия колонок или серий</i> | Имена команд | Линейное кодирование | <code type="inline">Имена команд</code> | | Имена папок | Нет выделения | Имена папок | | Подчёркивание | Курсив. Например: "Используйте that, чтобы ввести ограничительное условие.
Не печатайте поверх.." | Используйте <i>that</i>, чтобы ввести ограничительное условие.
<i>Не</i> печатайте поверх.. | Имена исключений | Линейное кодирование | <code type="inline">Имена исключений</code> | | Имена файлов | Нет выделения | Имена файлов | Вызовы функций | Линейное кодирование | <code type="inline">Вызовы функций</code> | | Элементы управления графического интерфейса | Жирный шрифт. Например: "В меню Установка, щёлкните Установить новую функцию > Закончить." | В меню Установка, щёлкните <b>Установить новую фукнцию</b> > <b>Закончить</b>. | HTML-теги или сегменты кода | Линейное кодирование | <code type="inline">HTML-теги или сегменты кода</code> | Интерфейсы | Линейное кодирование | <code type="inline">Интерфейсы</code> | Ключевые слова (например, static) | Линейное кодирование | <code type="inline"> Ключевые слова (например, static)</code> | | Названия журналов | Курсив. Например: "См. соответствующую статью в LinuxToday ..."." | См. соответствующую статью в <i>LinuxToday</i> ... | Текст сообщений или подсказки, адресованные пользователю | Линейное кодирование | <code type="inline">Текст сообщений или подсказки, адресованные пользователю</code> | Методы | Линейное кодирование | <code type="inline">Методы</code> | Объекты | Линейное кодирование | <code type="inline">Объекты</code> | | Имена пути | Нет выделения | Имена пути | | Термины, определяемые в контексте | Курсив | <i>Термины, определяемые в контексте</i> | Текст, вводимый пользователем | Линейное кодирование | <code type="inline">Текст, вводимый пользователем</code> | | "Названия руководств" | Кавычки | "Названия руководств" | Типы (Types) (например, int или long) | Линейное кодирование | <code type="inline">Типы (Types) (например, int или long)</code> | | URL | Нет выделения | URL | | Переменные | Курсив. Например: "... где myname
представляет Ваш идентификатор пользователя..." | ... где <i>myname</i> представляет Ваш идентификатор пользователя... | XML-теги или сегменты кода | Линейное кодирование | <code type="inline">XML-теги или сегменты кода</code> |
|
Передача Вашей статьи или руководства developerWorks
Когда Вы закончите Ваш шедевр, он готов к отправке редактору developerWorks. Отправьте по e-mail XML-файл Вашей статьи
или руководства (вместе с прилагающимися изображениями или образцами кода программ) Вашему редактору. Подробные рекомендации и
советы по созданию и передаче графических файлов для Вашей статьи см. по адресу
"
Иллюстрирование Вашей статьи или руководства для developerWorks: Советы для авторов по графическому оформлению."
Если у Вас возникнут какие-либо вопросы или проблемы, пожалуйста
свяжитесь с Вашим редактором
и получите дополнительную помощь.
Загрузка | Описание | Имя | Размер | Метод загрузки |
|---|
| IBM developerWorks author package, V5.3 | author-package-v5.3-20060214.zip | xxxKB | HTTP |
Ресурсы Научиться
Получить продукты и технологии
Обсудить
-
Форма передачи контента: Передайте идею статьи или руководства в developerWorks,
и вступите в контакт с редактором developerWorks.
Об авторе | | | Данный контент доводится до Вашего сведения сотрудниками редакции developerWorks. |
Выскажите мнение об этой странице
| |
