Opinionated tips based guide for writing bachalor and magister diploma thesis on FIT ČVUT. It’s written in Czech, because that way it can attract more readers from FIT ČVUT.
- LaTeX a sazba
- Používejte XeLaTeX
- Věnujte minimálně den přípravě sazby (před samotným psaním)
- Oficiální šablona je doporučení
- Naučte se používat svůj operační systém
- Používejte nástroj Arara
- Používejte nástroj latexmk
- Používejte (nějakou) vlnu
- Nesázejte ukázky kódu proporcionálním písmem
- Co můžete, dejte vektorem/textem
- Vložte zadání práce do PDF
- Nemějte práci v jednom velkém souboru
- Ostatní
Budou tu hlavně technické tipy. Pokud vás zajímají rady o obsahu, čtěte například blog Adama Herouta.
Používejte XeLaTeX
Unicode je dnes standard, přestaňte používat obyčejný LaTeX, který s ním neumí pracovat.
Určitě vás nebaví neustále řešit l\'etaj\'ic\'i akcent, T1 kódování a podobné výmysly minulého tisíciletí.
XeLaTeXu se nemusíte bát, přestože oficiální šablona je pro obyčejný LaTeX, její úprava je poměrně triviální. Oficiální šablona neexistuje, ale můžete se inspirovat třeba touto. Pokud se naučíte šablonu mírně upravit, získáte i znalosti potřebné na to, abyste fixli nějaký případný problém, který se časem objeví.
Pak můžete ve zdrojáku používat normální Unicode, háčkyčárky, „uvozovky“ bez maker, Русский, 💩, cokoliv.
Stejně tak pro citace používejte Biber, který také podporuje Unicode.
(Pokud používáte TeX bez LaTeXu, stačí použít XeTeX.)
Setkávám se s tím, že studenti něco nějak napíšou a před odevzdáním se to snaží naprasit do školní latexové šablony. Doporučuji předtím, než začnete psát, tomu (Xe)LaTexu minimálně den věnovat a všechno si hezky připravit. Může se to zdát jako ztráta času, ale pokud budete průběžně sázet, hned uvidíte, že něco vypadá blbě, že by bylo lepší to udělat takhle apod.
Sazbě je třeba se samozřejmě věnovat i na samotném konci, zkontrolovat, že vám nic nepřetéká z řádku, že všechno vypadá, jak má, apod.
Věnujte chvilku času osvěžení si práce s LaTeXem. Jako poměrně stručný, ale zároveň vyčerpávající návod lze doporučit LaTeX Wikibook.
„Ale ono to pak vypadá jinak než v šabloně.“
„Šablona mi tam napsala v českém textu Listing, to mám nechat?“
Nehroťte to, šablona je doporučení, pokud něco uděláte jinak a budete k tomu mít dobrý důvod (vypadá to líp, je to modernější, lépe se s tím pracuje, je to čitelnější apod.), je to více než v pořádku.
BTW Šablona samotná je na fakultním GitLabu a není problém poslat tam Merge Request (gitlabí ekvivalent githubího Pull Requestu), pokud máte úpravu, která je prospěšná všem.
Pokud na vás TeX křičí, že mu chybí foo.sty, naučte se, kde ho vzít.
Na Fedoře stačí udělat dnf install 'tex(foo.sty)', na jiných distribucích a operačních systémech to půjde nějak podobně.
IMHO není v pořádku se s chybovou hláškou o chybějícím souboru/balíčku TeXu v posledním ročníku FITu nedokázat vypořádat.
Používejte nástroj Arara
„Když vám nefungují odkazy a obsahy, projeďte to TeXem ještě jednou.“ Děláte to ručně? Vyzkoušejte nástroj Arara, který to udělá za vás. Na začátek zdrojáku dejte (něco jako):
% arara: xelatex
% arara: biber
% arara: xelatex
% arara: xelatexPřípadně s obyčejným LaTeXem:
% arara: pdflatex
% arara: bibtex
% arara: pdflatex
% arara: pdflatexA pak použijte příkaz arara foo.tex. Arara je papoušek, který papouškuje příkazy za vás.
Používejte nástroj latexmk
Výstup LaTeXu je dlouhý a nečitelný, těžko v něm najít to, co stojí za to číst. LaTeXmk vám hezky napíše, co se podělalo, nebo čemu věnovat pozornost.
Latexmk: List of undefined refs and citations:
Label `hateoas' multiply defined
Biber warning: Duplicate entry key: 'BSD3' in file 'library.bib', skipping ...
Biber warning: I didn't find a database entry for 'foo' (section 0)Zároveň se účelem trochu kryje s Ararou, protože vám taky ten dokument projede víckrát. Každopádně ho můžete používat i z Arary, například takto:
% arara: xelatexmkVlna vkládá nedělitelné mezery (vln(k)y, ~) za neslabičné předložky (a i jinam, kam nedělitelná mezera patří, ale ne úplně všude).
Použít vlnu je dobré, protože nemusíte na nedělitelné mezery tolik myslet.
Můžete použít různé vlny: Olšákovu vlnu, xevlnu pro XeTex, chytřejší luavlnu pro LuaTex (umí tituly, jednotky apod.).
Vlna se dá používat jako řádkový program, kterému soubor předhodíte (vlna), nebo jako balíček přímo ve zdrojáku (luavlna a xevlna):
% XeLaTeX:
\usepackage{xevlna}
% XeTeX:
\input xevlna.sty(Z Facebooku to vypadá, že si všichni kompilují vlnu sami, tak jen připomenu, že na Fedoře opět stačí dnf install /usr/bin/vlna nebo dnf install 'tex(xevlna.sty)'.)
Nejen pokud používáte vlnu manuálně z řádky, je vhodný čas použít na to všechno Makefile, což vám ušetří hromadu práce.
To už jistě umíte.
…je to hnusné. A dělá to skoro každý. Nějaký výchozí listing balíček to tak totiž asi má ve výchozím stavu. Používá proporcionální písmo, ale zarovná ho jakoby neproporcionálně. Pokud víte, co je to kerning, vytečou vám oči z důlků.
A vůbec, použijte minted. Zvýrazňuje syntaxi a je mnohem modernější, hezčí a křupavější. Tady najdete nějaký použitelný setup.
\begin{listing}[htbp]
\caption{\label{code:foo}Minted: Nyní ještě křupavější}
\begin{minted}[bgcolor=codebg]{python}
# ... code here ...
\end{minted}
\end{listing}Výstup z terminálu, log? – text (listing), ne obrázek.
Graf, diagram? – vektor, ne bitmapa.
Kreslíte nějaké schéma rukou? Použijte výborný cartoonist.
Děláte vlastní grafy/diagramy/… s popisky? Použijte v popiskách stejné písmo, jako v práci! Ano, je to občas pakárna, zjistit, co to je za písmo, ale pokud používáte XeLaTeX, tak to vlastně víte.
Nejdokonalejší typografické integrace obrázků a diagramů do práce dosáhnete, pokud je vytvoříte rovnou pomocí (La)TeXu. K vytváření dvourozměrných i trojrozměrných grafů existuje vynikající balíček PGFPlots. Komplikovanější diagramy lze tvořit pomocí TikZ/PGF. První uvedený balíček je nadstavbou nad druhým, a lze je proto i všelijak kombinovat. Oba mají velmi dobře čitelnou dokumentaci se spoustou konkrétních příkladů. Navíc lze na webu najít řadu inspirativních ukázek (viz např. PGFPlots Gallery a TeXample.net).
Tam, kde je napsané „Sem vložte zadání práce,“ máte vložit zadání práce. Já vím, je to instrukce těžká na pochopení, a proto většina studentů v odevzdaném PDF nechává tuto instrukci, což je ostuda. Vložení zadání je jednoduché jak facka:
\RequirePackage{pdfpages} % v šabloně, jinak \usepackage
\includepdf[pages={1}]{zadani.pdf}Náš odevzdávací systém, který máme všichni tak rádi, to nějak umí udělat za vás, což je super, ale pokud chcete to PDF použít i jinde, bylo by stejně lepší to udělat ručně. Jak to ten sytém dělá (jestli vymění první stranu, nebo jen první stranu, která obsahuje magický text), těžko říct, protože je to magie (proprietární black box). Navíc automagicky vložené zadání v BPM má hrozně nízké DPI. O důvod víc, proč to udělat v TeXu.
Doporučuji nemít práci v jednom mega .tex souboru, ale rozdělit ji do několika menších souborů (např. na úrovni kapitol) a ty potom vkládat pomoci \input.
Pokud chcete překládat jenom některou z takto vložených kapitol (např. kvůli časové náročnosti překladu kapitoly, na které už nepracujete, nebo chcete-li školiteli poslat jenom již hotovou část) a chcete zachovat správné číslování, použijte \include a \includeonly.
Nejen pro kód implementační části, i pro text vaší práce (každou tu věc samozřejmě v samostatném repozitáři).
Pomůže vám to, když něco přestane fungovat.
Naučte se používat git bisect, bude se to hodit.
Pokud použijete GitHub nebo fakultní GitLab, váš vedoucí vám může přímo v jednotlivých commitech komentovat změny a nemusíte ho otravovat a posílat mu dokola e-mailem PDFko :)
Ideálně použijte repozitář v režimu public, pokud nejste vázání nějakou smlouvou o výhradní licenci. Z vašeho zdrojáku mohou spolužáci čerpat tipy, jak něco udělat, a vaše práce stejně bude nakonec veřejná.
Tady jen pozor, aby vám kamarádi nebo vedoucí neposílali Pull Requesty, práci musíte vypracovat sami.
Tady záleží na názoru, ale já v 3D labu chci po svých studentech, aby vytvářeli implementační část práce jako svobodný software. Pokud neděláte práci pro firmu, která vám to zakáže, je to dobrá volba, projekt pak uvidí například firmy, ve kterých (třeba) budete chtít pracovat.
Zvolte si licenci jakou chcete – kašlete na prohlášení, máte právo (pokud neuzavíráte s někým smlouvu o exkluzivitě) odevzdat škole práci s nějakým prohlášením a tu stejnou práci dát na GitHub s MIT/GPL/… licencí. Pokud chcete použít prohlášení, které se podobá GPL, zvolte prohlášení 4 (…osoby jsou oprávněny Dílo užít jakýmkoli způsobem, který nesnižuje hodnotu Díla a za jakýmkoli účelem … licenci alespoň ve výše uvedeném rozsahu a zároveň zpřístupnit zdrojový kód takového díla…).
V repozitáři se softwarem používejte anglické commit message, komentáře, proměnné. Dejte tam anglické README. Kolemjdoucí by neměl poznat, že to je implementační část české bakalářky/diplomky (pokud to tam samozřejmě nenapíšete).