Pull to refresh

Как я диплом в LaTeX писал с GitHub, Docker и TravisCI

Open source *LaTeX *PDF

Еще со времен обучения в университете я использовал LaTeX для оформления лабораторных и курсовых работ. Познакомился впервые с LaTeX на Coursera, на курсе "Документы и презентации в LaTeX".


В этой заметке я расскажу, как я писал диплом с помощью LaTeX и почему я использовал GitHub, Docker и TravisCI.


Но зачем?


Предисловие


Мой путь редактирования и создания документов начался с Microsoft Word, наверное как и у многих. После перехода с Windows на Linux я без труда стал использовать сначала OpenOffice, а потом LibreOffice, который в моих задачах не уступал по функционалу Word.


Немного больно было, когда написав какой-нибудь реферат в компьютерном зале библиотеки в OpenOffice, несешь его на распечатку на админский компьютер с Microsoft Word, а у тебя слетает все форматирование. В то школьное время мне никто не объяснил того, что можно сохранить документ в PDF и печатать без проблем, это я уже сам узнал, когда учился в университете и нужно было печатать документы чуть ли не каждый день.


Вернемся к LaTeX, до его использования, все что я слышал о LaTeX, это то, что с его помощью пишут статьи в научные журналы из-за того, что он очень удобен для работы с формулами. Те кто думают так же, рекомендую посмотреть курс на Coursera, возможно он изменит ваше мнение, мне например он очень понравился.


Hello, World на LaTeX:


\documentclass{article}
\begin{document}
Hello, World!
\end{document}

Кстати с помощью LaTeX можно делать и презентации. Вот тут можно посмотреть множество примеров как могут выглядеть эти презентации.


Бакалаврский диплом с LaTeX


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


Поначалу я использовал LaTeXila в качестве IDE, в котором сборка проекта осуществлялась одной кнопкой, можно было подключить проверку правописания, но он у меня иногда вылетал и тормозил, поэтому я стал использовать Sublime Text вместе с Makefile.


Пример Makefile:


all: build run

build:
    latexmk -xelatex -synctex=1 main.tex
run:
    xreader main.pdf &
clean:
    rm *.aux *.fdb_latexmk *.fls *.log *.out *.synctex.gz *.toc

Все исходники хранил в git, для удобства коллаборации с научным руководителем использовал GitHub. Структура проекта была очень простой, в файл main.tex подключались преамбула и остальные главы, которые хранились в отдельном каталоге.


main.tex:


\documentclass[a4paper,14pt]{extarticle} % 14й шрифт
\input{inc/preamble} % Подключаем преамбулу

\begin{document}
\tableofcontents % Содержание 
\clearpage

\input{inc/0-intro} % Введение
\input{inc/1-pz}    % Постановка задачи
...
\input{inc/0-bibliography} % Библиографический список

\input{inc/a-app} % Приложение А
\input{inc/b-app} % Приложение Б
\includepdf{act}  % Подключение стороннего PDF-файла
\end{document}

Описание всех стилей и форматирование находится в файле preamble.tex, который подключается в самом начале документа.


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


Содержание
Содержание


Опишу свои плюсы при работе с LaTeX, по сравнению с WYSIWYG-редакторами:


  • удобная версионируемость (вместо диплом.odt, диплом_01.01.2015.odt, диплом_исправл_печать.odt — версионируемость в git и возможность откатиться на любой коммит)
  • при случайном нажатии чего-либо, верстка не слетает (у меня такое бывало)
  • гибкие настройки (которые не всегда доступны в WYSIWYG-редакторах или они неочевидны)
  • гомогенная среда для всего (исходники презентации лежат в том же репозитории, что и диплом)
  • возможность коллаборации (дипломный руководитель может смотреть в репозитории что изменилось со времен последней проверки)
  • удобно использовать как шаблон для множества различных документов
  • удобно включать такие вставки как исходный код например или дополнительные PDF-файлы

Вот пример того, как легко можно подключить в документ файл с исходным кодом:


\lstinputlisting[numbers=left]{inc/ddos-deflate/ddos.sh}

Подключенный исходный код в документ
Подключенный исходный код в документ


Минус использования LaTeX для меня только один — нужно потратить время для того, чтобы отполировать все до нужного результата. Я даже на мгновение захотел заморочиться, чтобы перерисовать все диаграммы и схемы нативным способом с помощью TikZ, но это требовало очень много времени, поэтому я спокойно использовал для этого Google Drawings и draw.io.


Успешно защитив бакалаврский диплом и получив некоторые знания по работе с git, GitHub, Makefile, гуглению по LaTeXStackExchange на английском, я забыл про диплом на пару лет, для того чтобы использовать свой шаблон для написания уже магистерского диплома.


Магистерский диплом


В то время когда я обучался в магистратуре, я уже стал увлекаться инструментами инженера, такими как Docker, стал практиковаться с инструментами Continuous Integration, изучать практики DevOps. Также мне было интересно красиво оформлять свои пет-опенсорс-проекты с красивыми README-файлами.


В целом, когда я приступил к написанию магистерского диплома, требования к оформлению не особо изменились, поэтому я взял шаблон своего бакалаврского диплома и доделал по мелочи, например такие пункты как список иллюстративного материала, перечень сокращений и прочее. При защите бакалаврского диплома мы использовали плакаты размером A1, а в магистерском нам уже разрешили использовать презентации в виде слайдов, поэтому слайды я также верстал с помощью LaTeX и beamer.


Презентация сверстанная с помощью LaTeX и beamer
Презентация сверстанная с помощью LaTeX и beamer


Увлекшись понятием CI я подумал, а почему бы не собирать при каждом коммите в репозиторий новый PDF? Подключение GitHub к TravisCI заняло буквально несколько минут. Хоть TravisCI не умеет напрямую работать с LaTeX, но зато прекрасно работает с Docker. Круто, подумал я, убью сразу несколько зайцев:


  • попрактикуюсь с написанием Dockerfile
  • смигрирую все LaTeX-пакеты в Docker (а их там немало и они довольно тяжелые)
  • попрактикуюсь с использованием TravisCI
  • помогу тем, кто вдруг когда-то захочет воспользоваться моим шаблоном на отличной от Linux ОС

Написание файла конфигурации для TravisCI, Dockerfile и редактирование Makefile заняло не очень много времени и получилось удобно.


Часть Makefile для запуска сборки проекта в Docker:


...
docker:
    docker build -t docker-latex .
    docker run -ti -v ${PWD}:/master-thesis:Z docker-latex bash -c "make build && make clean"
    docker run -ti -v ${PWD}:/master-thesis:Z docker-latex bash -c "make -C presentation && make -C presentation clean"

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


Релизы
Релизы


Оформив диплом в нужном для себя виде, я решил поделиться шаблоном с сообществом, по аналогии со своим бакалаврским. Решено было красиво оформить README-файл репозитория, ведь это лицо проекта. Человек который нашел твой проект в интернете должен по файлу README сразу же без труда разобраться как собрать проект и что с ним делать.


Файл README.md
Файл README.md


Скоро мне предстоит писать третий диплом и я думаю, что мой подход к его написанию ничуть не изменится и на его оформление я потрачу совсем мизерное количество времени. Учитывая то, что я пересел с Linux на Mac OS, переход будет абсолютно безболезненным, так как есть Docker.


Итоги


Обычная заинтересованность LaTeX'ом позволила мне немного больше погрузиться в эту сферу:


  • "набил руку" при работе с LaTeX, что в дальнейшем помогло сэкономить время при создании документов и презентаций
  • набрался опыта при работе с git и GitHub, пока работал с этими пет-проектами
  • использовал на практике такие вещи как Docker и TravisCI, что дало мне хороший толчок при погружении в DevOps
  • научился аккуратно оформлять свои пет-проекты

Ответы на потенциальные вопросы


Зачем хранишь в репозитории PDF-файлы?

Исключительно для того, чтобы человек, который зашел в репозиторий, мог не только посмотреть исходники, но и увидеть результат всего этого без скачивания релиза.


Почему не до конца автоматизированы многие вещи, например библиография?

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


Соответствует ли шаблон ГОСТ/ДСТУ?

Я руководствовался исключительно требованиями нормоконтроллера, поэтому не совсем.


Перевод статьи на английский язык на Medium.

Tags:
Hubs:
Total votes 77: ↑76 and ↓1 +75
Views 42K
Comments Comments 69