Сообщений 56

Оценить

Шаблон для верстки статей RSDN

Руководство пользователя версии 1.6

Автор: Виталий Брусенцев
The RSDN Group

Опубликовано: 17.12.2003
Исправлено: 13.03.2005
Версия текста: 1.6

Предисловие

Базовое оформление

Основной текст
Заголовки
Примечания, предупреждения и советы
Листинги программ
Автоматическая раскраска кода

Более сложное оформление

Вставка рисунков
Вставка списков
Вставка "сырого" XML-кода
Вставка таблиц
Вставка гиперссылок
Импорт старых/чужих документов в шаблон

Разное

Диалог свойств документа
Преобразование в XML
Просмотр сгенерированной XML-статьи
История исправлений и известные ошибки

О, сколько нам открытий чудных
Готовит просвещенья дух!..
А.С. Пушкин
(цитата всего лишь демонстрирует применение стиля "Epigraph")

Инсталлятор RSDN Authoring Pack

Предисловие

Данный шаблон предназначен для верстки статей в формат XML, принятый на сайте RSDN. Для этого достаточно набрать статью в документе MS Word на базе данного шаблона, соблюдая некоторые соглашения. После нажатия кнопки "Make XML" будет автоматически создан соответствующий XML-документ. С синтаксисом языка разметки RSDN ML можно ознакомиться в документации к пакету, но для выполнения верстки 99% документов его знание не потребуется.

Для того чтобы начать работу, просто создайте в MS Word новый документ на базе шаблона "RSDN Article.dot". Для этого в меню "Файл" необходимо выбрать пункт "Создать…" и найти значок шаблона. Другой способ — выбрать в меню RSDN Authoring Pack пункт "Создать новую статью".

Базовое оформление

Основной принцип построения документа следующий: необходимо использовать набор специфических стилей RSDN Article. Если вы нарушите это правило, конвертор выдаст предупреждение и покажет "проблемное" место документа.

Для установки стилей можно использовать как стандартные средства (например, выпадающий список "Стиль" панели "Формат"), так и специальную панель "Conversion", которая в удобном виде группирует средства разметки. Кроме того, существует ряд "горячих клавиш", которые ускоряют применение часто используемых стилей. О них рассказывается при описании соответствующих стилей шаблона.

СОВЕТ

Данный документ создан в шаблоне и является примером правильного оформления статьи. Он содержит все допустимые стилевые элементы и должен успешно конвертироваться в XML. Вы можете изучить его перед началом работы (файл Template.doc находится в каталоге Article установочного каталога RSDN Authoring Pack).

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

Основной текст

Для основного текста предназначен стиль "Paragraph". Он может содержать оформление жирным шрифтом, курсивом, подчеркиванием, ^{надстрочными} или _{подстрочными} индексами (или одновременно несколькими начертаниями, но без пересечения). Но избегайте других элементов оформления, так как они будут игнорироваться.

В тексте также допустимы следующие специальные знаки: <>&, которые автоматически заменятся при преобразовании на соответствующие символы XML.

Для быстрого превращения стиля текущего абзаца в стиль Paragraph служит сочетание клавиш Alt + ~.

Заголовки

Первый абзац статьи содержит ее заголовок и обязательно должен иметь стиль Title (или <H1>). Следующий за ним абзац может иметь стиль Subtitle (<H2>) и, в таком случае, в нем содержится подзаголовок статьи. Далее в тексте данные стили встречаться не должны.

Статья в RSDN ML делится на части, разделы и подразделы. Части статьи необходимо начинать с заголовка (стиль PART Header или <H3>). Дальнейший текст, вплоть до следующего заголовка, будет считаться частью (<PART>) статьи. Точно так же отмечаются начала разделов (SECTION Header или <H4>) и подразделов (SUBSECTION Header или <H5>).

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

Для быстрого превращения стиля текущего абзаца в заголовок нужного уровня служит сочетание клавиш Alt + <номер>, где номер – порядковый номер уровня заголовка. Например, нажатие Alt + 3 превратит текущий абзац в заголовок части статьи (<H3>).

Примечания, предупреждения и советы

Это примечание. Для него существует стиль "Note". Допустимо использовать форматирование.

Несколько абзацев подряд, имеющих стиль Note, склеиваются конвертором в один блок. То же самое справедливо для стилей Warning и Tip (см. далее).

ПРЕДУПРЕЖДЕНИЕ

Внимание! Оформляйте предупреждения стилем "Warning"!

СОВЕТ

Вот Вам хороший совет: оформляйте такие абзацы стилем "Tip".

Листинги программ

Ниже приведен пример программного листинга (с использованием стиля "Code"). В нем форматирование указывать недопустимо, но можно использовать различные стили для подсветки синтаксиса - "<COMMENT>", "<KEYWORD>", <ACCENT> и т.д. (это удобно делать с помощью панели Conversion).

Пример листинга кода на языке IDL

Добавлена поддержка именованных и сворачиваемых листингов кода. Для создания именованного листинга поместите перед ним абзац со стилем "Name" и требуемым названием. Если текст названия начинается с символа '+', листинг будет изначально свернут, а если начинается с '-', то листинг будет развернутым.

Автоматическая раскраска кода

Для автоматической раскраски выделите блок с текстом программы и выберите пункт меню Code панели Conversion с названием нужного языка. Если требуемого языка в меню нет, придется выбрать "None (manual)" и раскрашивать вручную. Если есть время и желание, можете добавить поддержку Ваших любимых языков в компонент CodeColorer и поделиться с общественностью.

ПРИМЕЧАНИЕ

Условный disp-интерфейс компонента раскраски содержится в приведенном выше листинге (dispid методов, на самом деле, роли не играют).

При автоматической раскраске поддерживаются только 3 элемента синтаксиса: строковый литерал, ключевое слово и комментарий. Все, что должен сделать компонент – это выделить такие элементы программы специальными тэгами: <str>…</str>, <kw>…</kw> и <com>…</com>, соответственно. Все остальное выполнит шаблон.

В меню Code панели Conversion отображаются до 10 языков, поддерживаемых компонентом CodeColorer. Весь список языков доступен при выборе пункта меню Language from list.... Для обновления списка языков (при установке новой версии компонента) необходимо выбрать пункт меню Refresh Menu.

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

Более сложное оформление

Вставка рисунков

Так как верстка статей производится, в-основном, для публикаций на веб-страницах, то в документ нужно вставлять не сами рисунки, а ссылки на них. Для этого необходимо нажать кнопку "Добавить рисунок" на панели Conversion. Выбрав нужный файл, необходимо нажать на стрелку выпадающего меню кнопки "Вставка" и выбрать пункт "Связать с файлом". Рисунок должен находиться в том же каталоге, что и результирующий xml-документ (фактически, в том же каталоге, что и исходный .doc).

Конвертор обрабатывает только inline-рисунки, то есть не плавающие, а встроенные в текст. Рисунки Word и объекты WordArt необходимо преобразовывать в обычные растровые рисунки, а лишь затем вставлять в документ.

В абзаце с рисунком не должно быть текста. Если же абзац содержит еще хоть какие-то символы, то такой рисунок воспринимается как нестандартное расширение RSDN ML (например, для представления сложных символов или мелких формул). По возможности, избегайте таких ситуаций — такие документы очень сложно верстать в журнал.

Поддерживаются названия (подписи) для рисунков. Для этого сразу после рисунка вставьте абзац со стилем "Name" и текстом названия.

Рисунок 1. Пример вставки рисунка в текст

Вставка списков

Для того чтобы вставить в документ ненумерованный список, необходимо:

Набрать абзацы элементов списка;
И оформить их стилем UL.

Для того чтобы вставить в документ нумерованный список, необходимо:

Набрать абзацы элементов списка;
И оформить их стилем OL.

Поддерживается только один уровень нумерации.

Вставка "сырого" XML-кода

Существует "пожарный" стиль XML TAG, позволяющий вставить блок XML-кода непосредственно в генерируемый документ. Используйте его в самом крайнем случае, так как переносимость документа при этом снижается. Если Вам необходимо вставить XML непосредственно в середину абзаца, придется набрать с помощью этого стиля абзац целиком. Кроме того, с его помощью можно вставить только теги тела статьи, но никак не служебные (типа <TRANSLATOR>).

ПРИМЕЧАНИЕ
Основные служебные теги заголовка (<TRANSLATOR>, <CONTRIBUTOR> и т.п.) вынесены в свойства документа (см. ниже).

Вставка таблиц

Для вставки таблиц в документ проще всего использовать панель Conversion.

Свойство таблиц	Поддержка в трансляторе
Заголовки строк и столбцов	Поддерживаются. Для придания любой ячейке статуса "заголовочной" необходимо закрасить ее в какой-либо цвет. Используйте для этого панель "Таблицы и границы".
Форматирование	Поддерживается. В обычной ячейке таблицы может находиться довольно много текста с разнообразным форматированием (и даже гиперссылками).
Несколько абзацев текста в ячейке	Не поддерживаются. А нужно ли?
Слияние ячеек	Будет поддерживаться, если вы подскажете мне, как обрабатывать такие таблицы Word. Кроме того, это ухудшит переносимость документа (в XSL-шаблоне такой поддержки нет).
Название таблицы (подпись)	Поддерживается. Для этого сразу после таблицы вставьте абзац со стилем "Name" и текстом названия.

Таблица 1. Поддержка таблиц в шаблоне RSDN Article

Вставка гиперссылок

Просто вставьте текст и оформите его как гиперссылку Word. Формат статей RSDN ML предусматривает три специальных типа ссылок:

Внешняя ссылка (атрибут ext): служит для указания внешних (по отношению к данной странице) документов. Открытие внешней ссылки в веб-браузере происходит в новом окне.
Файловая ссылка (атрибут file): служит для указания ссылок на файлы (например, архивы с исходным кодом к статье).
Ссылка HTML Help (атрибут chm): применяется для указания ссылок на документы формата HTML Help.

Тип ссылки (file, ext или chm) можно задавать при верстке. Для этого откройте диалог "Изменение гиперссылки" и введите нужный тип в поле "подсказка".

Импорт старых/чужих документов в шаблон

Если вы уже набирали какую-то статью иными средствами (или в старой версии шаблона), можно достаточно быстро перенести такой текст в шаблон RSDN Article и пользоваться всеми его преимуществами, включая почти-WYSIWYG верстку и автоматическую генерацию XML.

Для быстрой конвертации статьи в приемлемый для конвертора документ можно сделать так:

открыть документ в наиболее "смотримом" виде (для XML – в трансформаторе) и скопировать его текст;
создать в Word новый документ на базе шаблона;
вставить в него текст из буфера;
назначить необходимые стили.

Если в тексте преобладает сложное форматирование, можно заменять его "пачками", используя замену Word с указанием стилей. Для этого нужно выбрать в меню "Правка -> Заменить", нажать на кнопку "Больше" для дополнительных опций и использовать выпадающее меню "Формат…".

Если же преобладают текст, листинги программ и рисунки, присвойте всему вставленному тексту стиль Paragraph, а затем вручную разметьте абзацы другого стиля (прежде всего заголовки). При назначении стилей сильно помогает клавиша F4 (повторить последнее форматирование), поэтому стили лучше назначать группами - сначала заголовки, затем списки и т.д. Выделять весь текст абзаца для присвоения стиля не нужно, достаточно вставить в него курсор. Выделение требуется только для inline-элементов (Bold, Italic и т.д.) и для "раскраски" листингов.

Разное

Диалог свойств документа

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

Настройки запоминаются отдельно для каждого документа. Если вы хотите изменить значения по умолчанию, откройте для редактирования файл RSDN Article.dot и измените свойства в нем.

Не забудьте заполнить такие важные поля документа, как Abstract (аннотацию, или краткое изложение темы статьи), имя автора и его компанию.

Параметры конвертора

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

Заголовок документа

На вкладке "Заголовок" указываются авторские данные и происхождение статьи.

Поддерживается указание гиперссылок в угловых скобках: например,

John Smith <smith@microsoft.com>

транслятор разделит на имя и адрес e-mail. Если в гиперссылке присутствует знак "@", она транслируется как "mailto:", иначе - как "http://".

Можно также указать несколько имен (или названий) в одной строке, разделяя их запятыми, например:

Василий Пупкин <pupkin@mail.ru>, Иван Петров

Поле "компания" при этом считается общим для всех имен.

Кроме того, в диалоге свойств можно задать дополнительные тэги заголовка XML-документа, не предусмотренные конвертором (например, <COPYRIGHT>).

Суммарные сведения

На вкладке "Дополнительно" следует задать суммарные сведения о документе: ключевые слова (для правильной компиляции в CHM) и краткое содержание (abstract) документа.

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

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

После преобразования полученный XML будет сохранен там же, где и исходный документ, но с добавлением ".xml" в названии.

Пример: C:\My Articles\RSDN\new.doc будет конвертирован в C:\My Articles\RSDN\new.doc.xml

Просмотр сгенерированной XML-статьи

Вы можете просматривать сгенерированный XML-код с помощью локальной версии трансформатора статей RSDN. Если в свойствах шаблона установлена опция "отображать содержимое в виде HTML", то в каталоге с файлами статьи будет также создан (и открыт в MS IE) файл с именем сгенерированного документа и c расширением ".html", содержащий результат трансляции.

Пример: C:\My Articles\RSDN\new.doc.xml будет транслирован в C:\My Articles\RSDN\new.doc.html

Для этого должен быть установлен MS XML 3.0.

ПРИМЕЧАНИЕ

Опция "Генерировать короткое расширение файла" в настройках позволяет избавиться от двойного расширения сгенерированных документов. При ее включении будут сгенерированы, соответственно, файлы new.xml и new.html.

Используйте эту опцию, если нет опасности затереть существующие .xml- и .html- документы.

История исправлений и известные ошибки

Уничтожено множество ошибок и, несомненно, добавлены новые :). Если вы создали документ, при обработке которого транслятор выдает ошибку Visual Basic, пришлите его мне. В то же время, нарушив правила форматирования, вполне возможно создать документ, который будет преспокойно транслироваться в ill-formed XML. Это поведение не является ошибкой.

Что нового в версии 1.6:

Шаблон исправлен и протестирован для работы с Word XP;
Добавлена поддержка рисунков, встроенных в абзац (расширение RSDN ML).
Исправлен ряд мелких ошибок;
Улучшена поддержка символов Unicode;
Устранено зацикливание на некоторых статьях (завершающихся абзацем со стилем CODE);
Исправлен компонент раскраски синтаксиса (вызов компонента больше не приводит к необходимости каждый раз сохранять шаблон).

Что нового в версии 1.5:

Инсталлятор на русском :)
Автоматически генерируется "анонимный" раздел <PART>, если Ваша статья начинается не с заголовка.
В меню Code добавлен новый пункт Last Colorer Action (shortcut по умолчанию – Alt+Q). Как свидетельствует из названия, он здорово облегчает верстку, начиная со второго участка кода ;)
Добавлена опция генерации коротких расширений (.xml и .html вместо .doc.xml и .doc.xml.html).
Добавлена поддержка полей "Ключевые слова", "Адрес обложки" и "Путь к рисункам" в свойствах документа (вкладка "Дополнительно").
Теперь в диалоге свойств документа все символы &,<,>," обрабатываются корректно. Не изменяется только содержимое полей с путями к файлам и поле "Дополнительный XML в заголовке документа". Не забудьте, что в полях типа "Автор" символы <,> имеют специальное назначение.
Также добавлена правильная (надеюсь) обработка спецсимволов в тексте гиперссылок и абзацев Name.
Все поля текста в диалоге свойств теперь могут содержать более 255 символов (несколько килобайт точно умещаются).

В версии 1.4 содержатся следующие изменения:

Шаблон изменен для работы с новым компонентом CodeColorer.
Меню языков раскраски работает чаще, чем не работает :).
При генерации HTML-документов их заголовок соответствует заголовку статьи.
Из генерируемого XML исключен элемент xml-stylesheet.
Глобальные параметры (путь к конвертору и т.д.) сохраняются в реестре под ключом HKEY_CURRENT_USER\Software\VB and VBA Program Settings\RSDN\Authoring.
Шаблон распространяется в виде дистрибутива в составе RSDN Authoring Pack.

Исправления в версии 1.3c:

Устранен пропуск абзацев, следующих сразу за листингами кода – ошибка появилась в версии 1.3.
Исправлена некорректная обработка ошибок при трансляции в HTML – ошибка появилась в версии 1.3.

Исправления в версии 1.3:

Добавлена поддержка уровней структуры в стили заголовков. Теперь можно, например, просмотреть содержание документа, выбрав в меню «Вид» пункт «Структура» и отображая первые 4 уровня.
Добавлены «горячие клавиши» для стилей заголовков (Alt+1 – Alt+5) и стиля Paragraph (Alt+~).
Значительно ускорена обработка листингов кода.
Устранено "замораживание" индикатора прогресса при конвертировании документа в Windows XP. Никогда бы раньше не подумал, что придется реализовывать обычный Message Pump в коде на VBA :)
Пустые ячейки таблиц больше не приводят к прерыванию процесса конвертирования с ошибкой.
При автоматической раскраске кода разрывы строк обрабатываются корректно.
При просмотре результата в HTML иконки в ссылках отображаются корректно.

На данный момент не исправлены известные проблемы:

"Осложненное" форматирование – например, пересекающиеся bold и <KEYWORD> элементы – может привести к генерации неправильного XML (с пересекающимися тэгами).
Если Вы меняли свойства документа (имя автора и т.д.), то при попытке закрыть статью MS Word предложит ее сохранить. Если согласиться на это, он иногда может "повиснуть”. Такое поведение, скорее всего, связано, с ошибкой в Word. Рецепт: нажмите при этом кнопку "Отмена", сохраните файл статьи самостоятельно, а уж потом закрывайте документ. Все будет ОК.

Вот, пожалуй, и все. Приятной верстки!

Виталий Брусенцев,

12.12.2003

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