Kompilacja szablonu
Z szablonu można korzystać na dwa sposoby:
- w przeglądarce, za pomocą narzędzia Overleaf;
- lokalnie, samodzielnie instalując wymagane pakiety i kompilując szablon.
Z uwagi na prostotę użycia, rekomenduję Wam korzystanie z Overleafa, gdy tylko jest to możliwe (tzn. gdy dostępna tam wersja nie jest zbyt stara w porównaniu do wersji dostępnej na repozytorium).
Niezależnie od tego, na każdej z tych platform szablon można skompilować za pomocą jednego z trzech popularnych kompilatorów LaTeXa:
- pdfTeX;
- LuaTeX;
- XeTeX.
Najlepsze rezultaty daje kompilacja za pomocą LuaTeXa; pdfTeX daje wynik bardzo podobny do LuaTeXa, ale nie przenosi automatycznie jednoliterowych wyrazów do nowej linii. Kompilacja za pomocą XeTeXa jest niezalecana z uwagi na niedoskonałą obsługę czcionek. Więcej informacji nt. kompilatorów znajduje się w tym rozdziale.
Szablon jest dostępny na platformie webowej Overleaf, co umożliwia korzystanie z niego bez konieczności instalacji TeXa na własnej maszynie.
Niestety wersja dla Overleafa nie zawsze jest aktualna, z uwagi na długotrwały proces aktualizacji: po wysłaniu zgłoszenia do supportu, pracownik Overleafa musi samodzielnie obejrzeć uploadowany szablon i ręcznie go zatwierdzić. Na dzień 15.01.2020, wersja dostępna na Overleafie pokrywa się z aktualną wersją stabilną 2.1.0 i zawiera wszystkie niezbędne funkcje. Ale warto wiedzieć, że czasem wersja na Overleafie może być przestarzała.
Dotychczas Overleaf wykorzystywał TeX Live 2018, ale 23 stycznia 2020 roku Overleaf zaktualizował go do wersji 2019.
Jeżeli stworzyłeś swój projekt przed 23 stycznia 2020 roku, to wystarczy go sklonować. Nowa kopia projektu będzie wykorzystywała już TeX Live'a 2019.
Wersja 2019 jest niezbędna, jeżeli korzystasz z funkcji \captionsetup. Możesz przeczytać o tym problemie tutaj.
Najnowsza wersja szablonu jest zawsze dostępna w zakładce Releases.
Aby skompilować szablon na własnej maszynie należy zainstalować sobie LaTeXa:
W innych konfiguracjach póki co nie próbowałem, w szczególności nie gwarantuję wsparcia dla systemów Apple'a. Z macOS-em radzisz więc sobie sam(a).
- Zainstaluj TeX Live z tej strony, klikając w link z napisem install-tl-windows.exe.
- Uruchom aplikację install-tl-windows.exe i zainstaluj TeX Live wraz ze wszystkimi pakietami
- Po zakończeniu instalacji, możesz zweryfikować jej poprawność: uruchom TeX Live Manager (GUI) lub tlmgr (w wierszu poleceń) i sprawdź, czy TeX Live ma zainstalowane poniższe pakiety:
biber latexmk collection-bibtex-extra collection-fonts-extra collection-latex-extra collection-lang-polish
UWAGA: TeX Live ze wszystkimi pakietami waży około 6,5 GB. Z tego powodu pełna instalacja zajmuje ponad półtorej godziny. Miej to na uwadze, planując sobie swój czas.
- Zainstaluj MikTeX ze strony głównej.
- Uruchom konsolę MikTeX Console i zaktualizuj wszystkie pakiety (zakładka "Updates").
- Zaintaluj poniższe pakiety (zakładka "Packages"):
- latexmk (do kompilacji),
- cm-super (do używania czionek o dynamicznej wielkości).
- W menu górnym "Tasks" kliknij kolejno:
- "Refresh file name database",
- "Refresh font map files",
- "Update package database".
Jeżeli czas oczekiwania na kompilację jest zbyt długi, należy przeinstalować MikTeXa.
Jeżeli masz na komputerze zainstalowane obie powyższe dystrybucje LaTeXa, TeXStudio i inne programy tego typu wykorzystują tą, której ścieżka znajduje się bliżej początku zmiennej środowiskowej PATH. Aby zmienić wykorzystywaną dystybucję należy zmienić kolejność tych ścieżek w PATH. Jeżeli jedna z nich znajduje się w zmiennej systemowej PATH, a druga w lokalnej - Path, usuń tą w systemowej i dopisz na końcu lokalnej.
Po zainstalowaniu LateXa, należy wyposażyć się jeszcze w IDE/edytor. Dostępne są dwa porządne edytory, w których szablon działa tak jak powinien: TeX Studio oraz VS Code. Możliwa jest również kompilacja z linii poleceń za pomocą Makefile.
Kompilacja szablonu na TeX Studio jest bardzo prosta: po zainstalowaniu LaTeXa, wystarczy uruchomić środowisko, a następnie przejść do: Opcje -> Konfiguruj TeX Studio -> Zbuduj, i ustawić:
- Kompilator domyślny: Latexmk
- Domyślne narzędzie bibliografii: Biber
Następnie kompilujesz szablon wciskając F5 i wszystko powinno działać bezbłędnie out of the box.
Jeżeli wynikowy szablon PDF nie zawiera bibliografii, skompiluj plik "*.bib", wciskając F8, a następnie znowu F5.
Aby VS Code poradził sobie z kompilacją LaTeXa, należy zainstalować dla niego wtyczkę LaTeX Workshop. Proces kompilacji kodu do pliku PDF uruchamiany jest automatycznie po każdym zapisie.
Niestety, w VS Code są pewne problemy z wtyczką do podglądu PDF w czasie rzeczywistym: często po skompilowaniu szablonu obraz się nie odświeża i należy ręcznie zamknąć kartę i otworzyć ją ponownie.
Kompilacja za pomocą "latexmk" w VS Code wykorzystuje Perla. Aby skompilować szablon za pomocą tego właśnie pakietu, należy zainstalować Perla. Zalecany jest open-source'owy Strawberry Perl. To samo tyczy się Atoma.
Można również skompilować szablon z linii poleceń za pomocą Makefile:
make pdf
albo
make lua
dla kompilacji z użyciem LuaTeX.
Na Windowsie make jest dostępny w msys, instalujesz go najlepiej za pomocą git-scm. Można go również pobrać za pomocą chocolatey. W tym celu:
- Uruchom konsolę PowerShell i wykonaj komendę:
Set-ExecutionPolicy AllSigned - Zainstaluj chocolatey według tej instrukcji. Po wpisaniu komendy
choco -?powinny ukazać się informację o wersji chocolatey. - Wykonaj w cmd.exe na prawach administratora komendę:
choco install make.
Możliwa jest kompilacja z użyciem trzech głównych kompilatorów: pdfTeX, LuaTeX oraz XeTeX. Pewne funkcje dostępne są jednak tylko w niektórych kompilatorach:
- kompilacja na pdfTeX oraz LuaTeX daje prawie takie same rezultaty, co - dzięki zastosowaniu techniki microtypingu i innych takich bajerów - gwarantuje epicki wygląd całego dokumentu.
- Na LuaTeX dodatkowo działa funkcja automatycznego przenoszenia jednoliterowych wyrazów do nowej linii, zgodnie z tradycyjnym zaleceniem polskiej typografii. Funkcja ta nie działa na pdfTeX, ze względu na brak możliwości oskryptowania dokumentu w języku Lua. Kompilacja LuaTeX-em jest jednak również znacznie dłuższa niż w pdfTeX.
- kompilator XeTeX daje możliwość stosowania własnych czcionek, czego nie zapewnia pdfTeX. Niestety, na XeTeX-u niedostępna jest część niskopoziomowych funkcji TeX-a, przez co, jeśli chodzi o końcowy rezultat, jestem w stanie zagwarantować co najwyżej dramat. Dlatego, jeżeli masz potrzebę zastosowania innego kompilatora niż pdfTeX (do czego nie zachęcam, bo nie ma po co) - to ogranicz się raczej do LuaTeX-a.
Zalecam zatem następujący workflow:
- Bieżąca kompilacja podczas tworzenia dokumentu w pdfTeX;
- Kompilacja końcowej wersji za pomocą LuaTeX-a.
Powyższe zalecenia dotyczą obu sposobów korzystania z szablonu: w przeglądarce (Overleaf) oraz lokalnie.