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

* [Быстрый старт](#Быстрый-старт)
* [Компиляция черновика](#Компиляция-черновика)
* [Простые ошибки](#Простые-ошибки)
* Установка
  * [В Ubuntu с TexLive внутри контейнера DockerTex](#В-ubuntu-с-texlive-внутри-контейнера-dockertex)
  * [В Ubuntu](#В-ubuntu)
  * [В Debian](#В-debian)
  * [В Fedora](#В-fedora)
  * [В Gentoo](#В-gentoo)
  * [TeXLive на Linux в обход привязанных к конкретному линуксу пакетам](#texlive-на-linux-в-обход-привязанных-к-конкретному-линуксу-пакетам)
  * [В MacOS 10.10 и выше](#В-MacOS-1010-и-выше)
  * [Установка шрифтов PSCyr](#Установка-шрифтов-pscyr)
    * [Рабочий способ установки в Ubuntu 15.10](#Рабочий-способ-установки-в-ubuntu-1510)
    * [Установка в MacOS 10.x](#Установка-в-macos-10x)
    * [Рабочий способ установки в Debian 9](#Рабочий-способ-установки-в-debian-9)
* [Сборка PDF из командной строки](#Сборка-pdf-из-командной-строки)
* Разное
  * [Пакеты и версии LaTeX](#Пакеты-и-версии-latex)
  * [Редактирование текста](#Редактирование-текста)
  * [Форматирование исходного кода](#Форматирование-исходного-кода)
  * [Сжатие файлов](#Сжатие-файлов)
  * [Пересборка pdf для типографии](#Пересборка-pdf-для-типографии)
  * [Отчёт о времени сборки](#Отчёт-о-времени-сборки)
  * [Сборка графики `.tikz`](#Сборка-графики-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`](https://ctan.org/pkg/mylatexformat)).
Это позволяет ускорить сборку ещё приблизительно в 1.5 раза (на повторную сборку
черновика диссертации на компьютере с процессором Intel i5 требуется около двух
секунд).

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

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

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

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

## Установка

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

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

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

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

```bash
sh install-dockertex.sh
```

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

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

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

```bash
dockertex make
```

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

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

```bash
dockertex make clean
```

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

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

```bash
dockertexstudio
```

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

### В Ubuntu

> Протестировано на Ubuntu 19.04.
> Для LTS-версий рекомендуется использование [DockerTex](#В-ubuntu-с-texlive-внутри-контейнера-dockertex)

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

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

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

```bash
sudo apt-get install texlive-full
```

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

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

### В Debian

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

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

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

### В Fedora

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

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

```bash
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](http://mscorefonts2.sourceforge.net/). Например, так:

```bash
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](https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/issues/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,
которая не позволит собрать проект. Необходимо
[создать собственный репозиторий](https://wiki.gentoo.org/wiki/Custom_repository)
и скопировать в него ебилд от 456 версии, переименовав в соответствии с актуальной
(на данный момент это 464a). (Если просто скопировать ебилд под новым именем
в тот же самый главный репозиторий, то при очередном `emerge --sync` он будет перезатерт.)
- Стилевой файл `impnattypo.sty`, необходимый для сборки проекта, отправлен мейнтейнерами
в пакет `dev-texlive/texlive-langfrench`, поэтому кроме основных пакетов необходимо
установить и его.

### TeXLive на Linux в обход привязанных к конкретному линуксу пакетам
[How to install «vanilla» TeXLive on Debian or Ubuntu?](http://tex.stackexchange.com/a/95373) —
инструкция на английском языке, как ставить TeXLive на Linux в обход привязанных
к конкретному линуксу пакетам (на примере Debian и Ubuntu).

### В MacOS 10.10 и выше
Для установки в среде MacOS достаточно установить пакет MacTeX
[отсюда](https://tug.org/mactex/mactex-download.html). После установки
необходимо добавить пути к установленным файлам в переменную окружения `PATH`,
например, так:

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

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

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

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

### Установка шрифтов PSCyr
PSCyr — это пакет красивых русских шрифтов для LaTeX. К сожалению, его нужно
устанавливать отдельно. Если он у вас не установлен, то ничего страшного —
шаблон заработает и без него. Ну лучше бы его всё-таки поставить. Инструкции по
установке PSCyr для различных конфигураций приведены
[в файле `PSCyr/README.md` внутри
репозитория](https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/blob/master/PSCyr/README.md).
Если вы не нашли подходящую вам инструкцию, но смогли выполнить установку
самостоятельно, то большая просьба
[поделиться](https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/pulls)
вашими наработками.

#### Рабочий способ установки в Ubuntu 15.10
(компиляция из [инструкции на welinux](https://web.archive.org/web/20190609183954/http://welinux.ru/post/3200/)
и файлов, которые есть в шаблоне)

Нужно скачать шаблон, найти в папке PSCyr файл pscyr0.4d.zip и распаковать его
содержимое куда угодно. Чтобы не переписывать пути, папка с содержимым должна
называться PSCyr, а не pscyr, как в архиве. Затем надо зайти в
терминал, перейти к тому каталогу, где лежит папка PSCyr с содержимым, и
выполнить команды из вышеупомянутого руководства:
```bash
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. Для этого выполняем
```bash
kpsewhich -expand-var='$TEXMFLOCAL'
```
С вероятностью около единицы результат будет `/usr/local/share/texmf/`.
Копируем всё туда:
```bash
sudo cp -R ./PSCyr/* /usr/local/share/texmf/
```
Ну и подключаем:
```bash
sudo texhash
updmap --enable Map=pscyr.map
sudo mktexlsr
```

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

```bash
#!/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`:

```bash
sudo bash ./install.sh
```
#### Рабочий способ установки в Debian 9

Аналогично тому как в Ubuntu не проходит, возникают сложности с правами доступа
к некоторым файлам. Разбираюсь в чем дело. Выводит в лог следующее сообщение:
```bash
/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`](../common/setup.tex)).

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

## Разное

### Пакеты и версии LaTeX
* Шаблон по умолчанию включает ряд распространённых пакетов, чтобы вы могли
сразу ими пользоваться. Однако, на вашей машине какие-то пакеты могут быть не
установлены. Если вам они не нужны, то вы можете их просто удалить (команда
`\usepackage{<имя пакета>}`).
* Лучше всего использовать актуальные и полные версии LaTeX-дистрибутивов, это
поможет избежать многих проблем. Например, [MikTeX](http://miktex.org/download)
2.9.6361+ для Windows или [TeXLive](http://www.tug.org/texlive/acquire.html)
2017+ для множества ОС.

### Редактирование текста
* Если у вас ещё не сформировались предпочтения по LaTeX-редактору, то обратите
внимание на [TeXStudio](https://texstudio.org/#download),
существующий для всех основных платформ.
* Некоторые редакторы (в том числе TeXStudio) позволяют подключить проверку
грамматики с помощью [Language
Tool](http://wiki.languagetool.org/checking-la-tex-with-languagetool) (есть
поддержка русского языка). Полностью от ошибок он не спасёт, но поиск простых
случаев облегчает. Например, в предложении «Как правило слон больше черепахи.»
он попросит поставить запятую, если одно и то же слово используется подряд (или
с интервалом в несколько слов) — LT второе слово подчёркнет и при необходимости
не сложно понять, есть смысл использовать синоним, может быть написать «этот,
который» или так и оставить. Подобных простых проверок —
[сотни](https://github.com/languagetool-org/languagetool/blob/master/languagetool-language-modules/ru/src/main/resources/org/languagetool/rules/ru/grammar.xml).

### Форматирование исходного кода
Программа [`latexindent`](https://www.ctan.org/pkg/latexindent) позволяет
форматировать исходный код `.tex` файлов.
Это делает код более читаемым и единообразным.

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

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

```bash
make indent INDENT_FILES=MyFILE.tex
```
По умолчанию настройки форматирования считываются из файла `indent.yaml`.
Для использования другого файла настроек, наберите в командной строке:
```bash
make indent INDENT_SETTINGS=mysettings.yaml
```

### Сжатие файлов
Размер выходных `.pdf` файлов может быть большим.
Особенно, если в тексте присутствует много рисунков с большим разрешением.
Программа [`gs`](https://ghostscript.com/) позволяет значительно уменьшить
размер `.pdf` файлов за счёт снижения качества растровых изображений.

Для сжатия файла диссертации можно использовать команду:
```bash
make compress-lowdpi
```
Сжатый файл будет создан с суффиксом `*_lowdpi.pdf`

По умолчанию, разрешение изображений снижается до 144 DPI. Изменить разрешение
и другие нюансы можно путём редактирования файла [`compress.mk`](../compress.mk#L36-L60)

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

```bash
make compress-lowdpi COMPRESS_FILE=somefile
```

### Пересборка pdf для типографии
Типографии могут выдвигать специальные требования к pdf файлам. Наиболее типичными являются:
 * отсутсвие прозрачности
 * задание всех цветов в CMYK
 * использование формата PDF версии 1.3

Для приведения pdf в соотвествие с данными требованиями можно использовать команду:
```bash
make compress-cmyk
```
Принцип работы и возможные побочные эффекты описаны в [`compress.mk`](../compress.mk#L64-L143).

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

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

```bash
make synopsis TIMERON=1
```

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

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

В процессе создания графики с использованием библиотеки [`tikz`](https://en.wikipedia.org/wiki/PGF/TikZ) требуется частая компиляция исходного файла.
Производить её вместе с остальным текстом довольно затратно по времени.

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

Например,

```bash
make tikz TIKZFILE=Presentation/images/tikz_plot.tikz
```

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

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

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