Pomalu už pojďme psát

Řešitelé bakalářek a diplomek se začínají ptát, jak to bude s tím psaním textové technické zprávy. Já jim odpovídám, že ještě není úplně kam spěchat, ale že nebude od věci pomalu začít. I ptají se dále, jak bych radil začít. A já jim říkám následující.

Pište text v LaTeXu. Bez výjimek. LaTeX je v mnoha ohledech zastaralý, divný, nepovedený, šílený. Málokdo by dokázal napsat tak zapálený a fundovaný hejt na LaTeX jako já. Přesto, na psaní delšího (a někdy i kratšího) odborného textu ho považuji za jedinou použitelnou možnost.

Na Windowsích mi dobře funguje kombinace MikTeX a TexStudio. Reference ve formátu .bib sbírám pomocí nástroje JabRef (ale dají se najít i jiné nástroje, třeba i takové, kvůli kterým nemůsíte počítač infikovat Javou). Dlouho jsem měl nechuť k editaci LaTeXu online, ale poslední dobou mě opravdu přesvědčil Overleaf.com. Pokud si s LaTeXem netykáte a potřebujete teď psát svoji bakalářku, Overleaf je správná volba. Možná je správnou volbou i pro pokročilé uživatele, protože rozpracovaný text můžete velice snadno sdílet se svým vedoucím, který nejen že uvidí vysázené PDF, ale může vložit i rychlé poznámky do předlohy a vaše komunikace bude daleko efektivnější.

Rozjeďte si školní šablonu (na FITu zde, mimochodem, od minulých let došlo k příjemným vylepšením). Teoreticky je možné psát text s nějakou jakoukoli šablonou a pak ho nechat přeformátovat do předepsané formy, ale zkušenost říká, že je lepší pokud možno hned formátovat do cílové podoby. Rozjeďte si tedy hned školní šablonu.

Comics Edition

Vytvořte komiksovou verzi celé diplomky (bakalářka je taky diplomka, dostává se za ni diplom). V první fázi se zaměřte na celkové pojetí textu – o čem že budete psát. Z toho velice rychle vyplyne, jaké budou kapitoly, podkapitoly, jak se budou jmenovat a jak budou dlouhé. Názvy kapitol a jejich sled se samozřejmě při psaní a zpřesňování změní. To nevadí, stejně sepište svoji nejlepší současnou představu a klidně celkem podrobně (do podkapitol a podpodkapitol). Je daleko lepší mít představu a vědět, že se mockrát změní, než představu nemít, nesepsat a psát nahodilosti.

Při tvorbě komiksové edice mně hodně pomáhají vhodné jednoduché příkazy. Nejsem žádný LaTeXový guru, jistě by stejná věc šla udělat nějak elegantněji (jestli víte, napište mi, vylepším si svoji sbírku). Následujících pár řádků mi však slouží věrně a intenzivně už pár let.

\usepackage{xcolor} 
\newcommand{\todo}[1]{\textcolor{red}{\textbf{[[#1]]}}}

\usepackage{blindtext}
\newcommand{\blind}[1][1]{\textcolor{gray}{\Blindtext[#1][1]}}

V textu se pak napíše něco jako:

\todo{Napsat dva až tři příklady použití.}
\blind[2]

Trvá to tak půl minuty a v textu je pak patrné, co se v textu vyskytne a jak dlouhé to asi tak bude. Výplňový text „lorem ipsum“ bude vysázený šedivě, aby bylo na první pohled patrné, co už je hotové napsané a co je jen výplň, která drží místo budoucímu textu.

Obrázky

Registrovat se na Overleaf, rozjet tam školní šablonu diplomky a nadhodit první představu o struktuře textu může být práce tak na hodinu – pokud jste jakživi nezavadili o LaTeX, možná na dvě. Dejte své diplomce ještě další dvě hoďky a promyslete, kde a jaké v ní asi budou obrázky (případně pseudokódy, tabulky, výpisy, schémata – to jsou vlastně taky takové divné obrázky).

Není myslím úplně obvyklé obrázky považovat za součást osnovy textu. Nicméně je to – u odborného textu – velmi užitečné a doporučeníhodné. Udělejte to tak.

Může se vám hodit TODO-image.pdf nebo nějaká vlastní obdoba téhož. Může se také hodit znát základní kód pro vložení obrázku:

\begin{figure}
  \tmpframe{\includegraphics[width=\linewidth]{TODO-image}}
  \caption{One image. \todo{Napsat pořádný titulek}}
  \label{fig:TODO}
\end{figure}

který – co asi? – vloží obrázek:

One Image

Aby uvedený kód fungoval, musí v nastavení dokumentu být tento fragment kódu:

\usepackage[utf8]{inputenc}
\usepackage{graphicx}

\setlength{\fboxsep}{0.005pt}
\newcommand{\tmpframe}[1]{\fbox{#1}}
%\renewcommand{\tmpframe}[1]{#1}

První řádek umožní korektní zpracování háčků a čárek češtiny (pokud toho nebylo dosaženo jinak, třeba když píšete dokument přímo v češtině). Druhý řádek použije balíček pro vkládání obrázků.

Poslední tři řádky definují příkaz \tmpframe, kterým radím obalit VŠECKY obrázky v dokumentu (diplomce). Rámuje těsným a tenkým rámečkem obrázky a před tiskem nebo odesláním dokumentu se vypne odkomentováním toho posledního řádku. Mimochodem, tady jsem si intenzivně vědom, že někdo, kdo s LaTeXem kamarádí, by stejnou věc vyřešil nějak čistěji, správněji; já jsem k tomu sílu nikdy neměl a příkaz mi léta slouží takto.

Slouží k čemu? Umožňuje najít obrázky, které mají kolem sebe bílý („neviditelný“) okraj, který pak dělá binec ve formátování obrázku. S použitím rámečku je najednou zřejmé, že obrázek potřebuje oříznout. „Nic takového nepotřebuji, nejsem magor, obrázky mám v pořádku,“ napadne nejspíš čtenáře tohoto textu. A bude se docela jistě mýlit, jako mnozí před ním. Už jsem viděl hodně diplomek, ale pouze tak jedna z dvacíti neměla formátování mírně nebo hodně zprasené vinou špatně oříznutých obrázků. Použijte těchto pár písmenek ve zdrojáku svého dokumentu a svět bude zase o trochu méně hnusné místo k žití (rozuměj ke čtení odborných textů).

Někdy obrázek nemusí být široký přes celý řádek (jako je tomu v příkladu výše díky width=\linewidth), ale má být menší. Není špatné ho vycentrovat a není špatné jeho velikost stanovit opět relativně k šířce řádku a ne v absolutních jednotkách (třeba milimetrech) – věřte, jednou si za to poděkujete.

\begin{figure}
  \centering
  \tmpframe{\includegraphics[width=0.6\linewidth]{TODO-image}}
  \caption{One image, $60\,\%$ of line width.  
    \todo{Napsat pořádný titulek}}
  \label{fig:TODO}
\end{figure}

A zde je výsledek – šedý text za obrázkem naznačuje, že obrázek je právě přes těch 60% šířky textu:

One Image

Správně oříznuté obrázky mimo jiné umožní snadné komponování složených obrázků. Dva grafy vedle sebe? Koláž 20 obrázků s příklady úspěšných/neúspěšných výstupů? Obvykle lepší i snazší skládat ve zdrojovém textu dokumentu a nikoliv slepením dílčích obrázků do jednoho, který se pak vloží jako celek:

\begin{figure}
  \tmpframe{\includegraphics[width=0.495\linewidth]{TODO-image}}\hfill
  \tmpframe{\includegraphics[width=0.495\linewidth]{TODO-image}}
  \caption{Two images. \todo{Napsat pořádný titulek}}
  \label{fig:TODO}
\end{figure}

\begin{figure}
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-image}}\hfill
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-image}}\hfill
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-image}}\\[1pt]
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-image}}\hfill
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-image}}\hfill
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-image}}
  \caption{A collage of multiple images -- perhaps samples of images that the system successfully processes. \todo{Napsat pořádný titulek}}
  \label{fig:TODO}
\end{figure}

Jednoduché a krásné a obvykle daleko lepší než nějaké tvořivé alternativy, které psače odborných textů napadají:

One Image

One Image

Podle žánru sepisované diplomky může dávat smysl si udělat vlastní specializovaný obrázek, který bude sloužit jako „placeholder“. Při psaní diplomky o mobilní aplikaci to bude třeba obrázek TODO-smartphone.pdf, použitý například tímto způsobem:

\begin{figure}
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-smartphone}}\hfill
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-smartphone}}\hfill
  \tmpframe{\includegraphics[width=0.327\linewidth]{TODO-smartphone}}
  \caption{A bunch of smartphones. 
    \todo{Sem vložit grafickou podobu konkurenčních aplikací}}
  \label{fig:TODO}
\end{figure}

One Image

Je dobrou praxí vkládat obrázky do jejich vlastní složky – obvykle nazvané images. Někdy používáme ještě druhou složku na generované grafy – plots. Obrázky ve složkách se vkládají úplně bez problémů:

\includegraphics[width=0.327\linewidth]{images/TODO-image.pdf}

nebo je možné nastavit cesty k obrázkům v záhlaví dokumentu:

\graphicspath{{images/}{plots/}{photos/}}

a složku pak není třeba zmiňovat, což většinou život zjednoduší, zřídka ovšem i zkomplikuje, ale na to si každý přijde sám.

Čisté TODO obrázky, o kterých zde mluvím, pak pisatel nahrazuje lepšími a lepšími a konkrétnějšími a konkrétnějšími verzemi. Není špatný nápad nějaké schéma, které v obrázku časem má být, nejdřív načrtnout tužkou, vyfotit mobilem a vložit jako „pokročilý placeholder“. Vznikne tím komiksová edice textu, která ještě lépe aproximuje finální tvar a přitom tvorba obrázku zabrala 5 minut, ne dvě hodiny, které pořádný, kvalitní vektorový výtvor nezřídka vezme.

Co tedy teď?

  1. Rozjeďte šablonu,
  2. nadhoďte kapitoly,
  3. načrtněte obrázky (pro začátek stačí ty obecné placeholdery ukazované v tomto textu a jejich titulky), a
  4. stavte se výsledek (nejlépe online nasdílený přes Overleaf) probrat za svým vedoucím.

Body 1-3 zaberou dvě-tři hoďky, žádné týdny psaní. Zajistí ale, že řešitel i vedoucí budou mít dost dobrou představu o tom, jak text – časem, po svém dokončení – bude vypadat, jak bude strukturován, které myšlenky dostanou kolik prostoru a tak dále. Tato představa se bude s dalším psaním a další tvorbou obrázků, tabulek a rovnic zpřesňovat a blížit cíli, na nějž řešitel bude hrdý a s nímž vedoucí bude souhlasit. A to – věřte mi – jednomu i druhému krásně projasní nejeden den.

Kategorie: diplomky