thesis/Readme/Installation.md

Установка и сборка

• Быстрый старт
• Компиляция черновика
• Простые ошибки
• Установка
  • В Ubuntu с TexLive внутри контейнера DockerTex
  • В Ubuntu
  • В Debian
  • В Fedora
  • В Gentoo
  • TeXLive на Linux в обход привязанных к конкретному линуксу пакетам
  • В MacOS 10.10 и выше
  • Установка шрифтов PSCyr
    • Рабочий способ установки в Ubuntu 15.10
    • Установка в MacOS 10.x
    • Рабочий способ установки в Debian 9
• Сборка PDF из командной строки
• Разное
  • Пакеты и версии LaTeX
  • Редактирование текста
  • Форматирование исходного кода
  • Сжатие файлов
  • Пересборка pdf для типографии
  • Отчёт о времени сборки
  • Сборка графики .tikz

Быстрый старт

1. Скачать шаблон в архиве или клонировать этот репозиторий.
2. Установить в вашей среде компиляции (например, в редакторе TeXStudio) движок библиографии Biber.
3. Скомпилировать dissertation.tex для получения диссертации и synopsis.tex для получения автореферата.
4. Убедиться, что всё успешно компилируется на вашем компьютере (Warning в *.log файле компиляции допустимы).
5. Если что-то не устраивает в оформлении — проверьте закомментированые возможности в файлах шаблона, много тонкостей в ГОСТ не определены. Например, в файле biblatex.tex можно отключить отображение в списке литературы полей DOI и ISBN, а в styles.tex строчкой \linespread{1.42} можно сделать полуторный интервал между строчками «как в Ворде» (несколько шире, чем общепринятый «типографский», поэтому на страницу влезет меньше текста).

Компиляция черновика

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

• в файле usercfg.mk добавить строчку DRAFTON ?= 1
• в файле setup.tex поменять значение параметра draft на 1
• запустить команду make draft или make DRAFTON=1

При этом шаблон будет собираться с некими отклонениями от ГОСТ, но в несколько раз быстрее (в основном отличия касаются оформления списка литературы). Этот режим удобен при промежуточных сборках, например, во время набора формул. Обратите внимание: нумерация работ в списке литературы при использовании режима черновика может быть неверной. Кроме того, при использовании biblatex в режиме черновика не ведётся подсчёт количества пунктов в списке литературы.

Пользователи Linux могут применять команды make dissertation-preformat и make synopsis-preformat, чтобы использовать предварительное форматирование преамбулы диссертации и автореферата (может потребоваться установка пакета texlive-mylatexformat). Это позволяет ускорить сборку ещё приблизительно в 1.5 раза (на повторную сборку черновика диссертации на компьютере с процессором Intel i5 требуется около двух секунд).

Простые ошибки

Если не собирается библиография, ссылки на литературу отображаются вопросами или жирными названиями:

1. Попробовать поменять параметр bibliosel в соответствующем файле setup.tex, подробнее читать «в случае проблем с библиографией».
2. Очистить папки проекта от прошлых временных файлов (*.aux, *.toc, *.bbl, *.bcf, *.synctex.gz и прочие подобные).
3. Убедиться, что в вашей среде компиляции (например, в редакторе TeXStudio) правильно выбран движок библиографии (в соответствии с параметром bibliosel в каждом из файлов setup.tex).
4. Провести несколько компиляций проекта.
5. Если ничего из предыдущих пунктов не помогло, запустить latexmk на главном файле автореферата или диссертации, или выполнить соответствующий make.

Если компилируется с ошибками, то изучение соответствующего *.log файла может помочь определить причину (как правило, ошибки вызваны отсутствием необходимых пакетов или их версий). Часто первая ошибка в *.log файле является первопричиной остальных.

Установка

В Ubuntu с TexLive внутри контейнера DockerTex

Протестировано в Ubuntu 16.04 LTS и Ubuntu 18.04 LTS

Для обеспечения максимальной воспроизводимости сборки проекта рекомендуется использовать специализиарованный Docker-контейнер от проекта dockertex, базирующийся на Debian Buster 10 и TexLive 2018, с минимальной модификацией (добавлением пакета шрифтов от Microsoft - ttf-mscorefonts-installer и набора шрифтов Liberation в виде пакета fonts-liberation). Образ контейнера объемом около 2.5 Гб будет загружен из сети, при этом с учетом этапа распаковки в системе потребуется около 8 Гб свободного места в каталоге /var.

Установка контейнера в вашу систему выполняется путем запуска соответствующего скрипта, находящегося в корне этого шаблона:

sh install-dockertex.sh

Далее необходимо выйти из системы и зайти снова (либо перезагрузиться).

После этого станут доступны две новых команды - dockertex и dockertexstudio. Для TexStudio будет создан ярлык с названием Docker TexStudio (texlive2018) в категории Office.

Команда dockertex используется для сборки проекта - диссертации, автореферата и презентации (по сути это make без аргументов):

dockertex make

После выполнения команды будут созданы три PDF-файла: dissertation.pdf, presentation.pdf и synopsis.pdf.

При необходимости можно запустить make clean:

dockertex make clean

Остальные аргументы make могут быть вызваны аналогично.

Команда dockertexstudio используется для запуска TexStudio из контейнера:

dockertexstudio

После открытия файла dissertation.tex и нажатия будет создан PDF диссертации.

В Ubuntu

Протестировано на Ubuntu 19.04. Для LTS-версий рекомендуется использование DockerTex

Для установки XeTeX в Ubuntu и необходимых дополнительных пакетов можно использовать команду:

sudo apt-get install make texlive-xetex texlive-generic-extra texlive-lang-cyrillic texlive-lang-french texlive-science fonts-liberation latexmk biber

или для установки полного комплекта программ:

sudo apt-get install texlive-full

Для использования шрифтов Microsoft требуется их установка. Например, для Ubuntu это можно сделать так:

sudo apt-get install ttf-mscorefonts-installer
sudo fc-cache -fv

В Debian

Протестировано на Debian 10.

Установка аналогична Ubuntu.

Для установки шрифтов Microsoft должен быть подключен репозиторий contrib.

В Fedora

Протестировано на Fedora 27.

Для установки XeTeX необходимо установить следующие пакеты:

sudo dnf install texlive-xetex latexmk texlive-hyphen-russian biber \
                    texlive-extsizes texlive-cm texlive-amscls texlive-nag \
                    texlive-polyglossia texlive-euenc texlive-multirow \
                    texlive-makecell texlive-ec texlive-was texlive-zapfding \
                    texlive-totcount texlive-totpages texlive-interfaces \
                    texlive-tocloft texlive-tabulary texlive-floatrow \
                    texlive-biblatex texlive-biblatex-gost texlive-cite \
                    texlive-bibtex texlive-impnattypo texlive-cleveref \
                    texlive-tabu texlive-mwe

Далее можно установить шрифты из набора Microsoft's Core Fonts. Например, так:

sudo dnf install http://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm
sudo fc-cache -fv

В Fedora 23 есть проблема (#84) с компиляцией библиографии с помощью biblatex и biber, поэтому необходимо переключиться на использование bibtex. Для этого в файле Dissertation/setup.tex переключите \setcounter{bibliosel}{1} в 0, чтобы получилось \setcounter{bibliosel}{0}. Ту же самую операцию повторите в файле Synopsis/setup.tex.

В Gentoo

В репозиториях Gentoo лежит относительно старая версия TeXLive и сопутствующих пакетов, однако особых проблем с ними возникнуть не должно. Следует учитывать лишь два момента:

• Устаревший dev-tex/latexmk (на 31.05.2019). В репозитории лежит версия 456, которая не позволит собрать проект. Необходимо создать собственный репозиторий и скопировать в него ебилд от 456 версии, переименовав в соответствии с актуальной (на данный момент это 464a). (Если просто скопировать ебилд под новым именем в тот же самый главный репозиторий, то при очередном emerge --sync он будет перезатерт.)
• Стилевой файл impnattypo.sty, необходимый для сборки проекта, отправлен мейнтейнерами в пакет dev-texlive/texlive-langfrench, поэтому кроме основных пакетов необходимо установить и его.

TeXLive на Linux в обход привязанных к конкретному линуксу пакетам

How to install «vanilla» TeXLive on Debian or Ubuntu? — инструкция на английском языке, как ставить TeXLive на Linux в обход привязанных к конкретному линуксу пакетам (на примере Debian и Ubuntu).

В MacOS 10.10 и выше

Для установки в среде MacOS достаточно установить пакет MacTeX отсюда. После установки необходимо добавить пути к установленным файлам в переменную окружения PATH, например, так:

export PATH=$PATH:export PATH=$PATH:/Library/TeX/texbin

Чтобы сделать эффект постоянным можно добавить эту строку в .bash_profile:

echo "export PATH=$PATH:export PATH=$PATH:/Library/TeX/texbin" >>~/.bash_profile

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

Установка шрифтов PSCyr

PSCyr — это пакет красивых русских шрифтов для LaTeX. К сожалению, его нужно устанавливать отдельно. Если он у вас не установлен, то ничего страшного — шаблон заработает и без него. Ну лучше бы его всё-таки поставить. Инструкции по установке PSCyr для различных конфигураций приведены в файле PSCyr/README.md внутри репозитория. Если вы не нашли подходящую вам инструкцию, но смогли выполнить установку самостоятельно, то большая просьба поделиться вашими наработками.

Рабочий способ установки в Ubuntu 15.10

(компиляция из инструкции на welinux и файлов, которые есть в шаблоне)

Нужно скачать шаблон, найти в папке PSCyr файл pscyr0.4d.zip и распаковать его содержимое куда угодно. Чтобы не переписывать пути, папка с содержимым должна называться PSCyr, а не pscyr, как в архиве. Затем надо зайти в терминал, перейти к тому каталогу, где лежит папка PSCyr с содержимым, и выполнить команды из вышеупомянутого руководства:

mkdir ./PSCyr/fonts/map ./PSCyr/fonts/enc
cp ./PSCyr/dvips/pscyr/*.map ./PSCyr/fonts/map/
cp ./PSCyr/dvips/pscyr/*.enc ./PSCyr/fonts/enc/
echo "fadr6t AdvertisementPSCyr \"T2AEncoding ReEncodeFont\"" > ./PSCyr/fonts/map/pscyr.map

Дальше надо узнать, где у вас локальный каталог texmf. Для этого выполняем

kpsewhich -expand-var='$TEXMFLOCAL'

С вероятностью около единицы результат будет /usr/local/share/texmf/. Копируем всё туда:

sudo cp -R ./PSCyr/* /usr/local/share/texmf/

Ну и подключаем:

sudo texhash
updmap --enable Map=pscyr.map
sudo mktexlsr

Установка в MacOS 10.x

1. Скачать файлы со шрифтами и распаковать их в одну папку.
2. Создать/отредактировать файл install.sh, чтобы он содержал следующее:

#!/bin/sh

INSTALLDIR=`kpsewhich -expand-var='$TEXMFLOCAL'`
mkdir -p $INSTALLDIR/{tex/latex,fonts/tfm/public,fonts/vf/public,fonts/type1/public,fonts/map/dvips,fonts/afm/public,doc/fonts}/pscyr
mv dvips/pscyr/* $INSTALLDIR/fonts/map/dvips/pscyr
mv tex/latex/pscyr/* $INSTALLDIR/tex/latex/pscyr
mv fonts/tfm/public/pscyr/* $INSTALLDIR/fonts/tfm/public/pscyr
mv fonts/vf/public/pscyr/* $INSTALLDIR/fonts/vf/public/pscyr
mv fonts/type1/public/pscyr/* $INSTALLDIR/fonts/type1/public/pscyr
mv fonts/afm/public/pscyr/* $INSTALLDIR/fonts/afm/public/pscyr
mv LICENSE doc/README.koi doc/PROBLEMS ChangeLog $INSTALLDIR/doc/fonts/pscyr

mktexlsr

echo "Map pscyr.map\n" >> $INSTALLDIR/web2c/updmap.cfg
updmap-sys

3. Запустить полученный скрипт с помощью sudo:

sudo bash ./install.sh

Рабочий способ установки в Debian 9

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

/usr/local/share/texmf/tex/latex/pscyr/pscyr.sty: Permission denied /usr/share/texmf/tex/latex/pscyr/pscyr.sty: Permission denied

Сборка PDF из командной строки

Сборку можно производить следующими командами:

• диссертация: latexmk -pdf -pdflatex="xelatex %O %S" dissertation
• автореферат: latexmk -pdf -pdflatex="xelatex %O %S" synopsis

Либо можно использовать make-файлы (движок xelatex): из корневого каталога выполнять

• make для сборки всего
• make dissertation для сборки диссертации,
• make synopsis для сборки автореферата,
• make presentation для сборки презентации для доклада,
• make dissertation-draft для сборки диссертации в режиме черновика,
• make synopsis-draft для сборки автореферата в режиме черновика,
• make synopsis-booklet для сборки автореферата для печати,
• make presentation-booklet для сборки презентации для печати,
• make presentation-handout для сборки раздаточных материалов,
• make draft для быстрой сборки диссертации и автореферата в режиме черновика,
• make release для сборки всего и внесения финальных *.pdf файлов в систему контроля версий git
• make clean очистка от временных файлов
• make distclean очистка всех генерируемых файлов (включая .pdf)
• make pdflatex сборка полной версии с движком pdflatex (несколько быстрее для автореферата, чем xelatex, движок для библиографии в соответствии с настройками setup.tex).

Презентация может собираться собираться любым из трёх движков: pdflatex, xelatex, lualatex.

Разное

Пакеты и версии LaTeX

• Шаблон по умолчанию включает ряд распространённых пакетов, чтобы вы могли сразу ими пользоваться. Однако, на вашей машине какие-то пакеты могут быть не установлены. Если вам они не нужны, то вы можете их просто удалить (команда \usepackage{<имя пакета>}).
• Лучше всего использовать актуальные и полные версии LaTeX-дистрибутивов, это поможет избежать многих проблем. Например, MikTeX 2.9.6361+ для Windows или TeXLive 2017+ для множества ОС.

Редактирование текста

• Если у вас ещё не сформировались предпочтения по LaTeX-редактору, то обратите внимание на TeXStudio, существующий для всех основных платформ.
• Некоторые редакторы (в том числе TeXStudio) позволяют подключить проверку грамматики с помощью Language Tool (есть поддержка русского языка). Полностью от ошибок он не спасёт, но поиск простых случаев облегчает. Например, в предложении «Как правило слон больше черепахи.» он попросит поставить запятую, если одно и то же слово используется подряд (или с интервалом в несколько слов) — LT второе слово подчёркнет и при необходимости не сложно понять, есть смысл использовать синоним, может быть написать «этот, который» или так и оставить. Подобных простых проверок — сотни.

Форматирование исходного кода

Программа latexindent позволяет форматировать исходный код .tex файлов. Это делает код более читаемым и единообразным.

Для форматирования пользовательских документов можно использовать команду:

make indent

Можно указывать другой файл для форматирования. Например, для форматирования только файла MyFILE.tex:

make indent INDENT_FILES=MyFILE.tex

По умолчанию настройки форматирования считываются из файла indent.yaml. Для использования другого файла настроек, наберите в командной строке:

make indent INDENT_SETTINGS=mysettings.yaml

Сжатие файлов

Размер выходных .pdf файлов может быть большим. Особенно, если в тексте присутствует много рисунков с большим разрешением. Программа gs позволяет значительно уменьшить размер .pdf файлов за счёт снижения качества растровых изображений.

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

make compress-lowdpi

Сжатый файл будет создан с суффиксом *_lowdpi.pdf

По умолчанию, разрешение изображений снижается до 144 DPI. Изменить разрешение и другие нюансы можно путём редактирования файла compress.mk

Сжать произвольный pdf файл somefile.pdf можно командой:

make compress-lowdpi COMPRESS_FILE=somefile

Пересборка pdf для типографии

Типографии могут выдвигать специальные требования к pdf файлам. Наиболее типичными являются:

• отсутсвие прозрачности
• задание всех цветов в CMYK
• использование формата PDF версии 1.3

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

make compress-cmyk

Принцип работы и возможные побочные эффекты описаны в compress.mk.

Отчёт о времени сборки

Для вывода на экран в конце сборки информации о затраченном времени можно использовать флаг TIMERON=1. К примеру, запуск команды

make synopsis TIMERON=1

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

Сборка графики .tikz

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

Для ускоренной компиляции файлов .tikz отдельно от остального шаблона предусмотрен рецепт make tikz. Для запуска компиляции рисунка требуется задать путь к файлу .tikz при помощи переменной TIKZFILE.

Например,

make tikz TIKZFILE=Presentation/images/tikz_plot.tikz

сгенерирует файл tikz_plot.pdf в корневой папке.

Генерация раздаточного материала

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

Для генерации раздаточных материалов в шаблоне предусмотрен файл presentation_handout.tex. Первым делом требуется сгенерировать саму презентацию presentation.pdf. Далее, в файле presentation_handout.tex надо добавить слайды с соответствующими комментариями при помощи макро \includeslide. Выходной файл presentation_handout.pdf генерируется при помощи команды

make presentation-handout