Назначение

В данном репозитории хранится шаблон и скрипты для автоматической вёрстки статей для Трудов ИПА РАН. Из текстовых исходных файлов в форматах .md (Markdown) и .bib (Bibtex) производятся файлы формата .docx, соответствующие требованиям журнала. Также из .docx производятся PDF-файлы.

Пример сгенерированной статьи (PDF).

Перечень файлов

Исходные файлы

• article.md — файл, составляющий текстовую часть статьи.

• article-template.docx — файл-шаблон, содержащий:

  • титульный лист
  • стили, используемые для форматирования текста

• article.bib — библиографические ссылки в формате Bibtex.

• gost-r-7-0-5-2008-numeric-iaa.csl — стилевой файл библиографического списка.

• pic.png, oc-plot.emf — иллюстрации для статьи.

• README.md — данное руководство.

Скрипты

• build-transactions.ps1 — PowerShell-скрипт, который делает следующее:
  • Вызывает Pandoc для конвертации .md-файла в формат docx с применением стилей из шаблона в формате docx и стилей библиографии в формате CSL;
  • С помощью Word и COM делает постобработку полученного документа;
  • Сохраняет результат в форматах docx и PDF.
• build-article.bat — файл для быстрого запуска build-transactions.ps1 со всеми необходимыми параметрами для сборки статьи.
• pandoc-article.bat — файл для преобразования статьи в формат docx без постобработки (работает быстрее, чем с постобработкой).
• .gitlab-ci.yml — настройки удалённого запуска сборки по коммиту в GitLab

Результаты сборки (отсутствуют в репозитории)

• article.docx, article.pdf — результат сборки статьи
• article-raw.docx — результат преобразования в docx без постобрабоки

Результаты сборки (в терминологии GitLab — артефакты) доступны по ссылкам из раздела «Pipelines». Есть и прямые ссылки:

• Перечень файлов наиболее недавней сборки.
• PDF-файл из наиболее недавней сборки (с предпросмотром).
• PDF-файл из наиболее недавней сборки (прямое скачивание).
• DOCX-файл из наиболее недавней сборки (прямое скачивание).

Инсталляция

Системные требования

1. Microsoft Word версии 2010 или выше, с сопутствующими ему COM-объектами в операционной системе. Проверялась русская локализация Word, но и английская тоже должна работать.
2. Pandoc версии 2.1.1 или выше. Дистрибутив Pandoc включает также фильтр pandoc-citeproc, необходимый в нашем случае. Внимание: для работы скриптов требуется, чтобы директория, в которой находится исполняемый файл pandoc.exe (как правило, это директория C:\Program Files (x86)\Pandoc) была указана в переменной окружения PATH.
3. pandoc-crossref — ещё один необходимый фильтр. Дистрибутив можно скачать с этой страницы. Внимание: исполняемый файл pandoc-crossref.exe требуется поместить в одну из директорий, указанных в PATH, например в вышеупомянутую C:\Program Files (x86)\Pandoc.
4. Microsoft PowerShell. Входит в Windows начиная с 7-й версии.
5. Шрифты компании «Паратайп»: PT Serif, PT Sans и PT Mono. Они бесплатны для скачивания, использования и распространения. Сгенерированные .docx файлы содержат эти шрифты внутри себя, что позволяет открывать эти файлы на системах, где эти шрифты не установлены. При отсутствии необходимости внедрения шрифтов отключите опцию -embedfonts в команде запуска build-transactions.ps1. (Внедрение шрифтов «утяжеляет» .docx файлы на несколько МБ.)
6. Система контродя версий Git. Строго говоря, не является обязательной, но её отсутствие сведёт на нет существенную часть преимуществ текстовых исходных файлов.

Необходима ОС Windows, преимущественно по причине использования COM. (Остальные вещи в той или иной степени существуют и на Linux и Mac OS X.) Тем не менее, Windows необходима лишь для автоматической вёрстки (в т.ч. удалённой через Gitlab CI), а редактировать исходные файлы можно в текстовом редакторе в любой операционной системе, обмениваясь файлами с другими пользователями через Git.

Системные настройки

1. Для выполнения PowerShell скриптов из файла требуется запустить PowerShell с правами администратора и выполнить следующую команду:

   set-executionpolicy remotesigned 

2. Для увеличения лимита памяти при запуске PowerShell в удалённом режиме требуется установить следующий ключ в регистре: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\ClientMaxMemoryPerShellMB в значение 512 или больше.

   Этот ключ требуется лишь при удалённом запуске, и лишь при версии Powershell меньше 3.0.

Использование

1. Клонируйте данный репозиторий на свою машину с Windows.

2. Запустите build-article.bat.

3. При успешном выполнении этого скрипта приступайте к редактированию .md и .bib файлов.

   Более полный по сравнению с данным примером набор приёмов для форматирования текста в Markdown и построения иллюстраций содержится в репозитории GOSTdown.

   Иллюстрации, не имеющие отношения к вашей статье, можно удалить.

   Файл .gitlab-ci.yml можно удалить, если вам не требуется удалённый запуск (см. следующий раздел).

4. Полученные .docx файлы не требуют, по замыслу, никакой дальнейшей ручной или автоматической обработки. Их можно отправлять в редакцию журнала; при желании их можно редактировать так же, как обычные документы, созданные вручную, но это не рекомендуется.

При необходимости сравнения .docx

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

pandoc original.docx -o original.md
pandoc modified.docx -o modified.md
<программа для сравнения текстовых файлов> original.md modified.md

Таким образом, изменения в .docx (по крайней мере, в текстовой части) не пройдут незамеченными.

Программ для сравнения текстовых файлов доступно множество; можно отметить Meld для Linux или WinMerge для Windows.

Удалённый запуск через GitLab CI (только для сотрудников ИПА РАН)

Следующий сценарий позволяет сотрудникам ИПА РАН работать над документом, не пользуясь ни Windows, ни Pandoc, вообще ничем, кроме Git и текстового редактора (и средства создания иллюстраций, если нужны иллюстрации).

1. Ответвите (fork) данный репозиторий (можете также переименовать в более актуальное для статьи название).

2. Каждая отдача файлов в репозиторий будет приводить к запуску сборки документа раннером Bill. Результаты сборки (артефакты) можно скачать из веб-интерфейса GitLab со страницы «Pipelines» (архив со всеми файлами или файлы по отдельности). Там же можно ознакомиться с сообщениями об ошибках, если сборка оказалась неудачной.

   Наличие PDF-файла наряду с docx позволит вам взглянуть на документ при отсутствии Word.

Авторы и права на использование

Авторы: Дмитрий Павлов (ИПА РАН) и Алёна Водолагина (ИПА РАН), при участии Даниила Аксима (ИПА РАН).

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

Связь

Замечания и предложения можно присылать на адрес dpavlov@iaaras.ru.