Сообщений 72    Оценка 1410 [+1/-0]         Оценить  
Система Orphus

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

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

Авторы: Брусенцев Виталий
Чистяков Владислав Юрьевич
Опубликовано: 22.06.2011
Исправлено: 26.04.2012
Версия текста: 2.0

Предисловие
Базовое оформление
Заголовки статьи
Таблица метаинформации статьи (на русском языке)
Пример заполнения таблицы метаинформации
Заголовок и таблица метаинформации статьи (на английском языке)
Заголовки частей и разделов статьи
Основной текст
Примечания, предупреждения и советы
Листинги программ
Автоматическая раскраска кода
Более сложное оформление
Вставка рисунков
Вставка списков
Вставка таблиц
Вставка гиперссылок
Раздел Ссылки/Литератур
Импорт старых/чужих документов в шаблон
Разное
Диалог свойств документа
Преобразование в XML
Просмотр сгенерированной XML-статьи
Антивирусное ПО
Поддерживаемые версии Word
История исправлений и известные ошибки
Возможные проблемы
Automation error

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

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

Предисловие

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

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

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

Для корректной работы шаблона требуется, чтобы на компьютере был установлен .Net Framework 3.5, Microsoft Word 2003 или выше, и настройки безопасности в Microsoft Word позволяли исполнять макросы (уровень Medium или Low (не рекомендуется)).

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

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

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

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

СОВЕТ

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

Генерируемый XML-код, если не нарушены правила форматирования, является подмножеством допустимого документа.

Есть возможность вносить непредусмотренные конвертором XML-элементы и прямо в статью (см. ниже описание диалога "Свойства" и стиля XML TAG). Но не следует использовать эту возможность без крайней необходимости.

Заголовки статьи

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

Таблица метаинформации статьи (на русском языке)

ПРИМЕЧАНИЕ

Зачем нужна метаинформация?

Она нужна для двух целей. Во-первых, метаинформация на русском языке требуется движку сайта www.rsdn.ru для генерации оглавления сайта, представления списков статей и формирования информации о статье отображаемой в начале статьи (информация об авторе и т.п.). Метаинформация так же позволяет улучшить поиск.

Кроме того метаинформация по статьям требуется для предоставления проекту www.elibrary.ru который ведет Российский Индекс Научного Цитирования (РИНЦ) в который входит наше издание RSDN Magazine, и соответственно, статьи с сайта www.rsdn.ru.

Для РИНЦ требуется несколько больше метаинформации, нежели отображается на нашем сайте. Так же для РИНЦ требуется метаинформация о статье на английском языке.

Учитывая это, просим серьезно подойти к вопросу заполнения метаинформации и перевода ее на английский язык.

Если у вас возникают проблемы или вопросы, связанные с заполнением или переводом метаинформации, обращайтесь за помощью по адресу mag@rsdn.ru.

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

Версия: номер версии статьи

Дата: дата окончания работы над статьей

Автор: ФИО: Фамилия Имя Отчество; E-Mail: адрес; Номер профиля на rsdn.ru:  число; Телефон: (код города) телефон; Адрес: почтовый адрес; Место работы: Сокращенное название места работы в именительном падеже; Должность: Название должности; Место учебы: наименование учебного заведения в именительном падеже; Научная степень: сокращенное название; Научное звание: звание;

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

Ключевые слова: ключвое слово 1; ключевое слово два; еще одно

Переводчик: ФИО: Фамилия Имя Отчество; E-Mail: адрес; Номер профиля на rsdn.ru:  число; Телефон: (код города) телефон; Адрес: почтовый адрес; Место работы: Сокращенное название места работы в именительном падеже; Должность: Название должности; Место учебы: наименование учебного заведения в именительном падеже; Научная степень: сокращенное название; Научное звание: звание;

Источник: Ссылка или название источника, где статья была опубликована впервые. Удалить, если статья еще нигде не публиковалась.

Предоставил: ФИО: Фамилия Имя Отчество; E-Mail: адрес; Номер профиля на rsdn.ru:  число; Телефон: (код города) телефон; Адрес: почтовый адрес; Место работы: Сокращенное название места работы в именительном падеже; Должность: Название должности; Место учебы: наименование учебного заведения в именительном падеже; Научная степень: сокращенное название; Научное звание: звание;

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

Описание полей разделов «Автор», «Переводчик», «Предоставил»

ФИО: Фамилия имя и отчество должны идти в указанной последовательности, быть в именительном падеже и не содержать никакой дополнительной информации.

E-Mail: Адрес будет опубликован в журнале (печатной версии и на сайте научного индекса цитирования), но не на сайте rsdn.ru. Если вы категорически против его публикации, то удалите это поле, но при этом вы будете обязаны указать почтовый адрес и/или телефон.

Номер профиля на rsdn.ru: Этот номер можно получить в командной строке браузера, если зарегистрироваться на сайте rsdn.ru под своей учетной записью (если ее нет, создайте ее), выбрать имя своей учетной записи в правом верхнем углу, удерживая Shift, нажать на ссылку «Файлы», и в появившемся окне броузера скопировать из адресной строки число, идущее за «?uid=».

Телефон: Необязательное поле, если указан E-Mail или почтовый адрес.

Адрес: Необязательное поле, если указан E-Mail или телефон (поля Телефон, Адрес и E-Mail нужны, чтобы с автором статьи могли связаться заинтересованые читатели, не имеющие доступа к онлайн-версии статьи).

Место работы: Место работы в именительном падеже. В этом поле не должно быть ни подразделения организации, ни адресов авторов, ни их должностей (т.е. ничего лишнего). Только место работы! Данная информация используется в индексе научного цитирования. Если вы учитесь и не имеете постоянной работы, то удалите это поле.

Должность: Должность в указанной (в поле «Место работы») организации. Удалите это поле, если вы только учитесь.

Место учебы: Место учебы (последнее, наиболее важное или текущее). Данное поле обязательно только для соискателей степеней и защищающих дипломы!

Научная степень: Удалите это поле, если вы не имеете научной степени. Примеры: КТН, КФ-МН. Список степеней и их сокращения можно взять здесь.

Научное звание: Удалите это поле, если вы не имеете научного звания. Примеры: Профессор, Доцент. Список званий можно взять здесь. Не путайте аналогичные должности и звания!

Пример заполнения таблицы метаинформации

Ниже приведен пример метаинформации для вымышленной статьи «Морзянка и мобильные устройства».

Версия: 1.0

Дата: 22.06.2011

Автор: ФИО: Сидоров Иван Петрович; Номер профиля на rsdn.ru:  123456; Место работы: ООО «Рога и Копыта»; Должность: Директор; Место учебы: СПбГУ; Научная степень: КТН; Научное звание: Доцент;

Автор: ФИО: Айсберг Пилагея Ивановна; Номер профиля на rsdn.ru:  654321; Место учебы: МГУ; Научная степень: Соискатель;

Аннотация: Статья посвящена разработке программного обеспечения для мобильных устройств с использованием секретных технологий кодирования морзянкой.

Ключевые слова: мобильные устройсва; морзянка

Обратите внимание на то, что обычно не имеет смысла редактировать поле «Дата», так как по умолчанию оно содержит автоматически обновляемое при записи Word-поле.

Заголовок и таблица метаинформации статьи (на английском языке)

Вслед за таблицей содержащей метаинформацию о статье на русском языке должны идти заголовок и подзаголовок на английском языке. Как и в случае русскоязычного заголовка, подзаголовок является необязательным. Эти заголовки должны иметь стиль H1 и H2 (или их аналоги описанные выше).

Вслед за заголовками на английском языке должна идти таблица содержащая метаинформацию по статье информация в которой должна быть задана на английском языке.

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

Имена разделов в англоязычной таблице должны оставаться на русском языке. Переводу подлежит только содержимое этой таблицы!

Заголовки частей и разделов статьи

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

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

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

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

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

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

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

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

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

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

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

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

СОВЕТ

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

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

Ниже приведен пример программного листинга (с использованием стиля «Code»). Вы можете использовать в коде символьные стили (т.е. стили, влияющие только на оформление символов, и не влияющие на форматирование параграфа):

Кроме того в коде может содержать оформление жирным шрифтом, курсивом, подчеркиванием, надстрочными или подстрочными индексами, но помните, что в коде, особенно в печатной версии статьи, эти выделения могут быть плохо заметны или незаметны вовсе. Особенно не стоит выделять участки кода жирным. Лучше использовать вместо этого стиль «<ACCENT>».

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

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

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

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

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

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

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

Конвертор второй версии поддерживает как inline-рисунки, так и встроенные в документ. Встроенные рисунки вынимаются из тела документа и помещаются в подкаталог (рядом с документом).

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

Directory of C:\PROJECTS\RSDN\MAG#5-2004

01-07-2005  17:18    <DIR>          .
01-07-2005  17:18    <DIR>          ..
01-02-2005  11:31    <DIR>          QnATextToSpeech
04-01-2005  14:15           107 008 qnatexttospeech.doc
04-01-2005  14:15            23 849 qnatexttospeech.xml

 Directory of C:\PROJECTS\RSDN\MAG#5-2004\QnATextToSpeech

01-02-2005  11:31    <DIR>          .
01-02-2005  11:31    <DIR>          ..
06-12-2004  01:00            15 828 sapi4voices.png
06-12-2004  01:02            13 276 sapi5voices.png
07-12-2004  22:23            27 697 TextToSpeech.zip 

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

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

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

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

Если рисунки изначательно были созданы в некотором векторном формате, то при предоставлении статьи приложите исходные версии этих рисунков. Они понадобятся при подготовке статьи к печати в журнале RSDN Magazine.

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


.

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

По возможности избегайте таких ситуаций — такие документы очень сложно верстать в журнал.

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


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

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

Чтобы вставить в документ ненумерованный список, необходимо:

Чтобы вставить в документ нумерованный список, необходимо:

  1. Набрать абзацы элементов списка.
  2. И оформить их стилем OL.
ПРИМЕЧАНИЕ

Кстати, обратите внимание на расстановку заглавных букв и знаков препинания в списках.

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

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

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

Таблица 1. Поддержка таблиц в шаблоне RSDN Article (теперь заголовок таблицы может располагаться над ней)

Свойство таблиц

Поддержка в трансляторе

Заголовки строк и столбцов

Поддерживаются. Для придания любой ячейке статуса "заголовочной" необходимо закрасить ее в какой-либо цвет. Используйте для этого панель "Таблицы и границы".

Форматирование

Поддерживается. В обычной ячейке таблицы может находиться довольно много текста с разнообразным форматированием (и даже гиперссылками).

ПРИМЕЧАНИЕ

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

Это может быть даже код!

def fahrenheitToCelsius(fahrenheit)
{
  5.0 / 9 * (fahrenheit - 32)
}

Название таблицы (подпись)

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

Теперь ячейки могут быть объединены по горизонтали.

И даже по вертикали!

Кроме того, ячейки могут содержать несколько абзацев.

Текст

Другой текст

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

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

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

Раздел Ссылки/Литератур

Элементы этого раздела следует помечать стилями «LiteratureListOL» или «LiteratureListUL». Разница между ними заключается в том, что первый стиль добавляет нумерацию, а второй нет. Чтобы назначить этот стиль вы можете выбрать пункты «Style\Сисок литературы (нумерованный)» или «Сисок литературы» из панели инструментов «Conversion» (которая появляется при открытии документа связанного с данным шаблоном).

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

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

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

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

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

Разное

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

Во второй версии шаблона диалогового окна свойств нет. Все сведения следует задавать в самом документе. Например, метаинформацию следует задавать в таблице метаинформации, идущей сразу за заголовком документа (см. соответствующий раздел).

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

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

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

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

Если файл уже имеет расширение «.xml», т.е. находится в формате Word ML, то к имени файла будет прибавлен суфикс «.rsdnml».

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

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

При нажатии кнопки «Make XML», после генерации XML-файла он автоматически подвергается трансформации в HTML и отображается в броузере, с которым ассоциировано расширение HTML.

Антивирусное ПО

Вторая версия шаблона использует макросы и COM-объект, написанный на .Net, для того чтобы производить обработку быстро и качественно. Однако это может вызвать проблемы, если вы используете антивирусное ПО или слишком высокий уровень безопасности в Word (выше Medium).

СОВЕТ

Признаком слишком высокого уровня безопасности является отсутствие диалога, запрашивающего разрешение использования макросов, при создании нового документа.

Поддерживаемые версии Word

Вторая версия шаблона поддерживает Microsoft Word 2003 и выше. Тестирование производилось в основном на Word 2003, так что если вы испытываете проблемы с шаблоном на других версиях Word, опишите, какую версию вы используете.

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

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

Возможные проблемы

Automation error

В некоторых случаях вы можете получить сообщение об ошибке «Automation error» и предложением начать отладку скрипта:


При нажатии кнопки «Debug» возникнет следующая картина:


Данная ошибка связана с тем, что на системе имеется несколько версий .NET Framework и приложение Microsoft Office (Word в нашем случае) не может определить какую версию .NET Framework требуется использовать.

Чтобы устранить данную проблему нужно положить рядом с WINWORD.EXE конфигурационный файл с именем WINWORD.EXE.config следующего содержания (готовый файл можно скачать здесь):

<?xml version="1.0"?>
<configuration>
  <startup>
    <supportedRuntime version="v2.0.50727"/>
  </startup>
</configuration>

По умолчанию WINWORD.EXE можно найти по пути %ProgramFiles%\Microsoft Office\OFFICE<номер версии>\WINWORD.EXE. Например, для Word 2003 по умолчанию путь будет: "e:\Program Files (x86)\Microsoft Office\OFFICE11\WINWORD.EXE". Это заставит Word использовать конкретную (2.0) версию .NET Framework, что устранит ошибку.


Любой из материалов, опубликованных на этом сервере, не может быть воспроизведен в какой бы то ни было форме и какими бы то ни было средствами без письменного разрешения владельцев авторских прав.
    Сообщений 72    Оценка 1410 [+1/-0]         Оценить