Шаблон для верстки статей RSDN версии 2.0 Руководство пользователя Версия: 2.0 Дата: 29.04.2016 Автор: ФИО: Чистяков Владислав Юрьевич; Номер профиля на rsdn.ru: 73; Место работы: ООО «К-Пресс»; Должность: Директор; E-Mail: vc@rsdn.ru Автор: ФИО: Брусенцев Виталий; Номер профиля на rsdn.ru: 818; E-Mail: retalik@rsdn.ru Аннотация: Статья описывает шаблон для Microsoft Word предназначенный для верски статей и преобразованию их в формат RSDN ML. В стать рассматриваются вопросы использования шаблона. Ключевые слова: шаблон верски статей; RSDN ML; RSDN Article 2.dot; Microsoft Word; The RSDN article template version 2.0 User manual Версия: 2.0 Дата: 29.04.2016 Автор: ФИО: Chistyakov Vladislav; Номер профиля на rsdn.ru: 73; Место работы: OOO «KPress»; Должность: Директор; E-Mail: vc@rsdn.ru Автор: ФИО: Brusentsev Vitaly; Номер профиля на rsdn.ru: 818; E-Mail: retalik@rsdn.ru Аннотация: This article describes the template for Microsoft Word for design articles at www.rsdn.ru (for conversion to RSDN ML format). In this article describe questions of usage of the template. Ключевые слова: template; RSDN ML; RSDN Article 2.dot; Microsoft Word; О, сколько нам открытий чудных Готовит просвещенья дух!.. А.С. Пушкин (цитата всего лишь демонстрирует применение стиля "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 Дата: 29.04.2016 Автор: ФИО: Сидоров Иван Петрович; Номер профиля на 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>». +Пример листинга кода на языке IDL dispinterface Colorer { // Коллекция поддерживаемых языков [id(0x00000003), propget] VARIANT Languages(); // Преобразует текст сообщения в HTML [id(0x00000002), vararg] VARIANT PrepareMessage( [in] VARIANT Text, [in] VARIANT OptionalArgs); // Преобразует фрагмент кода [id(0x00000001), vararg] VARIANT TranslateCode( [in] VARIANT [in] VARIANT [in] VARIANT Text в соответствии с синтаксисом Lang Text, Lang, OptionalArgs); }; Добавлена поддержка именованных и сворачиваемых листингов кода. Для создания именованного листинга поместите перед ним абзац со стилем «Name» и требуемым названием. Если текст названия начинается с символа '+', листинг будет изначально свернут, а если начинается с '-', то листинг будет развернутым. (пока не реализовано во второй версии шаблона) Автоматическая раскраска кода Для автоматической раскраски выделите блок с текстом программы и выберите из выпадающего списка, находящегося на панели инструментов Conversion, язык, которым будет подсвечен блок текста. Если требуемого языка в меню нет, придется выбрать "None (manual)" и раскрашивать вручную (или выбрать наиболее близкий язык и подкрасить недостающие части вручную). Если есть время и желание, можете добавить поддержку ваших любимых языков. Для этого следует обратиться к команде RSDN и заполнить полученный XML-файл. Использованный для раскраски язык запоминается в настройках шаблона. Если ваши статьи содержат листинги на одном и том же языке, то для раскраски последующих фрагментов кода достаточно нажать Alt + Q или кнопку «Подсветить» (на панели инструментов Conversion), и шаблон раскрасит текущее выделение таким же образом. Более сложное оформление Вставка рисунков Конвертор второй версии поддерживает как inline-рисунки, так и встроенные в документ. Встроенные рисунки вынимаются из тела документа и помещаются в подкаталог (рядом с документом). Для размещения на сайте необходимо, чтобы рисунок находился в подкаталоге, одноименном названию статьи, рядом с самой статьей. В этот же каталог надо помещать все архивы и другие файлы, идущие вместе со статьей, например: Directory of C:\PROJECTS\RSDN\MAG#5-2004 01-07-2005 01-07-2005 01-02-2005 04-01-2005 04-01-2005 17:18 17:18 11:31 14:15 14:15 <DIR> <DIR> <DIR> . .. QnATextToSpeech 107 008 qnatexttospeech.doc 23 849 qnatexttospeech.xml Directory of C:\PROJECTS\RSDN\MAG#5-2004\QnATextToSpeech 01-02-2005 01-02-2005 06-12-2004 06-12-2004 07-12-2004 11:31 11:31 01:00 01:02 22:23 <DIR> <DIR> . .. 15 828 sapi4voices.png 13 276 sapi5voices.png 27 697 TextToSpeech.zip Если вы вставляете картинки как ссылки, проследите, чтобы они лежали в соответствующем подкаталоге. Во второй версии шаблона не требуется прописывать пути к картинкам и вообще нет диалога настройки. Все, что нужно, теперь заполняется прямо в самом документе. Это не позволяет забыть что-то заполнить. Рисунки Word и объекты WordArt необходимо преобразовывать в обычные растровые рисунки, а лишь затем вставлять в документ. Если рисунки изначательно были созданы в некотором векторном формате, то при предоставлении статьи приложите исходные версии этих рисунков. Они понадобятся при подготовке статьи к печати в журнале RSDN Magazine. В абзаце с рисунком не должно быть текста. Если же абзац содержит еще хоть какие-то символы, то такой рисунок воспринимается как нестандартное расширение RSDN ML (например, для представления сложных символов или мелких формул): . По возможности избегайте таких ситуаций — такие документы очень сложно верстать в журнал. Поддерживаются названия (подписи) для рисунков. Для этого сразу после рисунка вставьте абзац со стилем "Name" и текстом названия. Рисунок 1. Пример вставки рисунка в текст Вставка списков Чтобы вставить в документ ненумерованный список, необходимо: набрать абзацы элементов списка; и оформить их стилем UL. Чтобы вставить в документ нумерованный список, необходимо: 1. Набрать абзацы элементов списка. 2. И оформить их стилем OL. Кстати, обратите внимание на расстановку заглавных букв и знаков препинания в списках. Поддерживается только один уровень нумерации. Вставка таблиц Для вставки таблиц в документ проще всего использовать панель Conversion. Таблица 1. Поддержка таблиц в шаблоне RSDN Article (теперь заголовок таблицы может располагаться над ней) Свойство таблиц Поддержка в трансляторе Заголовки строк и столбцов Поддерживаются. Для придания любой ячейке статуса "заголовочной" необходимо закрасить ее в какой-либо цвет. Используйте для этого панель "Таблицы и границы". Форматирование Поддерживается. В обычной ячейке таблицы может находиться довольно много текста с разнообразным форматированием (и даже гиперссылками). Во второй версии шаблона в ячейках таблиц можно размещать абзацы, содержащие практически любое форматирование. Это может быть даже код! def fahrenheitToCelsius(fahrenheit) { 5.0 / 9 * (fahrenheit - 32) } Название таблицы (подпись) Поддерживается. Для этого сразу после таблицы вставьте абзац со стилем "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 и т.д.) и для "раскраски" листингов. Разное Диалог свойств документа Во второй версии шаблона диалогового окна свойств нет. Все сведения следует задавать в самом документе. Например, метаинформацию следует задавать в таблице метаинформации, идущей сразу за заголовком документа (см. соответствующий раздел). Преобразование в 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, что устранит ошибку.