Opinionated tips based guide for writing bachelor’s and master’s 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
- Sjednoťte formátování pojmů
- 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 umí pracovat jen omezeně.
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, sazbě a (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.
Mohu doporučit balíček blindtext, který vám usnadní přípravu struktury práce.
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). Existují i nástroje na konverzi grafů do TikZu, například matplotlib2tikz pro pythonní Matplotlib.
Screenshoty webových stránek jdou také nahradit vektorem, stačí stránku s vhodným nastavením vytisknout do PDF, případně použít sofistikovanější nástroj, jako třeba wkhtmltopdf.
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, do FIT šablony přidejte pdfpages:
\RequirePackage{pdfpages}A nahraďte text "Sem vložte zadání.." příkazem:
\includepdf[pages={1}]{zadani.pdf}Viz příklad zde.
Update: Náš odevzdávací systém, který máme všichni tak rádi, to nějak umí udělat za vás. Pokud ale chcete PDF generované přímo ze zdroje použít i jinde, tato rada se vám stále hodí.
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.
Ve vaší práci se pravděpodobně bude vyskytovat mnoho různých pojmů: názvy tříd,
metod, funkcí, programů, knihoven, jména souborů… rozhodněte se, jak je budete
formátovat, a svého rozhodnutí se držte. Nikde není do kamene vytesáno, že
název funkce musí být v textu neproporcionálním písmem, v uvozovkách nebo
kurzívou, ale vypadá velmi neprofesionálně, pokud to je na jednom místě tak
a jinde jinak.
Stanovte si pravidla a nejlépe si je sepište. Když narazíte na nový druh pojmu, vytvořte si pro něj pravidlo. Pokud chcete být übercool, vytvořte si na jednotlivé druhy pojmů makra.
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).
Obyčejný papír je částečně průsvitný/průhledný a druhá strana je přes něj vidět. To nechceš. Dejte pár korun navíc za 100gramový papír. Vypadá to lépe.
Ano, je to tak: někdo to bude číst. Text by tak měl pomáhat čtenáři a měl by se ideálně dát přečíst nahlas tak, aby mu bylo rovnou rozumět. Kromě plovoucích prostředí (obrázky, tabulky) je třeba dodržovat pravidla klasické středoškolské slohovky tak, jak je všichni milujeme. Například: základním prvkem je věta končící tečkou a to i když píšeme výčty (ve většině případů). Pokud nemáme spisovatelské sklony, je lepší se nepouštět do větších souvětí a informace v klidu předat kratšími, ale jasnými větami. Psaní anglických pojmů, zvláště jejich skloňování či časování, nevypadá vůbec dobře. Některým anglicismům se zvláště v IT nelze vyhnout, ale je-li jazykem práce čeština, pak je to čeština a česko-anglický kočkopes jen naznačuje mezery v základním vzdělání. Anglické pojmy je vhodné používat pouze není-li ustálený český překlad či je k tomu jiný praktický důvod (který je vhodné uvést). Píšete-li práci anglicky, pak vězte, že nejste-li si svou angličtinou jistojisti, pak budete trpět o něco více, protože angličtina neodpovídá k češtině jedna k jedné a nelze překládat slovo po slůvku.
Psaní odkazů na literaturu je také důležité: věcná tvrzení musí být buď jasně odvozena nebo řečeno, kam se může čtenář podívat, aby je našel. Primárně NEjsou vhodné odkazy typu „odstavec…odstavec, poslední věta v odstavci zakončená tečkou. [1]“, kde [1] je vztaženo k něčemu neurčitému uprostřed odstavce. V tom případě čtenář neví, co má ve zmíněné literatuře hledat. Nejjednoduším způsobem je referenci uvést ve větě a jasně zmínit, k čemu se vztahuje: „Dle [1] lze všechny kočky zkompilovat.“ nebo „Pro detailnější informace o této problematice doporučujeme [1,3].“
Často se studenti ptají: „Mám v práci 5 (15, 50…) položek v seznamu literatury, stačí to?“ Postupujte obráceně: Každé tvrzení, které napíšete, musí být podloženo citací, nebo jste jej vyzkoumali ve své práci. Napsat: „TeX je nejpoužívanější sázecí systém v akademické sféře,“ aniž byste uvedli zdroj tohoto tvrzení, prostě není možné. Pokud se budete držet tohoto pravidla, nebudete mít s malým množstvím citací problém.