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

Данный шаблон предназначен для верстки статей в формат 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 нужны, чтобы с автором статьи могли связаться заинтересованые читатели, не имеющие доступа к онлайн-версии статьи).

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

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

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

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

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

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

Автор: ФИО : Сидоров Иван Петрович; Номер профиля на 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»). Вы можете использовать в коде символьные стили (т.е. стили, влияющие только на оформление символов, и не влияющие на форматирование параграфа):

• <COMMENT> – для выделения комментариев.
• <KEYWORD> – для выделения ключевых слов языка.
• <STRING> – для выделения строк.
• <ACCENT> – для выделения участков в коде, на которые нужно обратить внимание читателей.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ПРИМЕЧАНИЕ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Разное

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

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

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

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

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

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

СОВЕТ

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

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

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

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

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

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

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