Projekty ze softwarového inženýrství na FIT VUT: Projekt 2 — dokumentace

Softwarové inženýrství je spíše neuchopitelné, než-li nepochopitelné. Hlavní problém je v tom, že málokdo ví, co tato disciplína vlastně obsahuje. Softwarový inženýr stojí mezi programátorem a zákazníkem (člověkem, který programátorovi zadává práci — a možná i zaplatí). Součástí práce SI je plánování práce programátorům a nebo tvorba dokumentace (plánování práce lidem, kteří ji vytvoří). A právě tvorba dokumentace byla náplní druhého projektu k předmětu  IUS — Úvod do softwarového inženýrství na FITu VUT.

Vzhledem k tomu, co všechno z této oblasti mám již za sebou (dvě knihy a poměrně velké množství článků, diplomka, bakalářka…) jsem se tohoto projektu nebál. Úkolem bylo vytvořit technickou dokumentaci ke druhému projektu z IZP — Základy programování.

V tomto článku se trochu podrobněji podívám na některé technické řešení, která jsem použil. Dostali jsme k dispozici šablonu v TeXu, ale to bych nebyl já, kdybych si nenapsal vzhled vlastní.

Vzhled

Celý dokument je typu report, aby bylo možné používat dělení na kapitoly \chapter{}. Všechny balíčky se načítají pomocí souboru proj2.sty, abych oddělil preambuli. Vzhled dokumentu je definován s pomocí balíčku fancyhdr, který upravuje vzhled záhlaví a zápatí (nutné samozřejmě použít \pagestyle{fancy}) a dost se podobá všem mnou vytvořeným dokumentům tohoto typu. Zvolil jsem písmo palatino pro patkovou rodinu a helvetiku pro bezpatkové. Mám ty dva fonty celkem rád 😉

Krom klasických balíků, které používá snad každý (ASM, geometry, babel, natbib či hyperref) dále používám balíček color, xcolor či microtype. K čemu jsou balíčky color a xcolor je poměrně jasné — color umí pracovat s barvami, zatímco xcolor definuje barvy jménem (red, blue, atd.).

To balíček microtype, spíše tedy jeho práce, tak zřejmá není. Mikro-typografie se zabývá typografií na úrovni jednotlivých glyfů, tedy vzdálenosti mezi písmeny (neupravuje tak kerningové páry, ale mezery obecně. A to z jednoho důvodu — aby vše vypadalo pěkně. Dále upravuje zalamování řádku. Interpunkční znaménka (tečka, čárka, spojovník), mají jinou optickou váhu. Pokud tedy řádek nekončí písmenem, ale interpunkcí, vypadá pravý okraj nerovný, ale zlehka „rozvlněný“. Při detailu to sice vypadá, že jsou znaménka více vpravo, než by měly být, ale při pohledu na celý odstavec toto bude srovnáno — jedná se o konečný výsledek.

Taky si definuji některé vlastní příkazy

\newcommand{\e}[1]{\mathrm{e}^{#1}}
\newcommand{\imag}{\mathrm{i}}
\newcommand{\dx}{\,\mathrm{d}}
\newcommand{\lb}{\,\mathrm{lb}}
\newcommand{\gb}[1]{\colorbox{lightgray}{\texttt{#1}}}
\newcommand{\up}[1]{\ensuremath{^\textrm{\scriptsize#1}}}

převážně pro práci s matematikou a příkaz \gb, který vytvoří šedý boxík (používám jej pro „poznámky“ a \up, který vysází text horním indexem v antikvě (rovném řezu) bez nutnosti přepínání do matematického režimu.

Začátek dokumentu

Ke vzhledu vše, pojďme se podívat na jednotlivé části práce a její řešení. Celá práce je rozdělena na tři celky — preface (překládá se to jako předmluva, ale je to titulka, obsah, seznam obrázků a podobné ptákoviny. Za tím následuje vlastní text dokumentace —  úvod, analýza a řešení problému, navržené testy pro ověření funkčnosti a konečně popis vlastního řešení a závěr (a seznam literatury). Třetí část, appendix (dodatky), obsahuje metriky kódu, grafy a schémata. Takovéto rozvržení bylo nutné z prostého důvodu — dokumentace byla neuvěřitelně dlouhá. Třicet stran textu a obrázků (a všeho dalšího) by bylo neúnosné a nejspíše neobhajitelné. Proto jsem obrázky (grafy a schémata) vložil do přílohy, která může být mnohem delší, než vlastní text. Může být a taky téměř je.

Tvorba titulky byla jednoduchá — de facto se jednalo o centrovaný různě veliký text a jeden obrázek.

\pagenumbering{roman}
\begin{titlepage}
\thispagestyle{empty}
\vspace{2cm}
\begin{center}
{\huge\textsc{Vysoké Učení Technické v Brně}}\\
\vspace{0.5cm}
{\Large\textsc{Fakulta Informačních Technologií}}\\
\vspace*{2.8cm}
\includegraphics[width=3.8cm]{obrazky/logo}\\
\vspace*{2.8cm}
{\Large\textsc{Dokumentace k projektu 2 do předmětů IZP a IUS}}\\
\vspace{1cm}
{\sc\huge{Iterační výpočty}}\\
\vspace{1cm}
{\LARGE\textsc{Bc. Petr Šafařík}}\\
{{xsafar14}}\\
\vspace{6.6cm}
{\Large\textsc{Brno 2010}}
\end{center}
\end{titlepage}

\newpage
\normalsize

Vysázíme Obsah a Seznam obrázků:

\tableofcontents %Obsah
\listoffigures   %Seznam obrazku

A vysázíme typografickou konvenci:

\newpage\thispagestyle{plain}
\vspace*{\fill}
\subsection*{Typografická konvence}
\begin{itemize}
\item \emph{Kurzivou} jsou psány zásadní termíny či podstatná slova.
\item \texttt{Neproporciální písmo} je použito v~případě názvů...
\item \texttt{[Neproporciální font]} v~hranatých závorkách...
\item \gb{Šedé pozadí}\, je použito pro zvýraznění...
\item Matematické funkce a~konstanty jsou sázeny antikvou.
\item $\mathcal{K}$aligrafický $\mathcal{F}$ont je užit...
\end{itemize}
}

Uznávám, typografická konvence byla možná zbytečná, ale mám rád, když má čtenář jasně definované, co je co.

Hlavní obsah dokumentace

Nebudu zde kopírovat zdrojáky, připadá mi to v tuto chvíli bezúčelné. Grafická změna se děje v záhlaví/zápatí, kde jsem aktivoval fancy, restartoval číslování stránek, přesunul jej do pravého rohu a začal sázet arabskými číslicemi (oproti malým římským v preface a velkým římským v dodatcích).

Problém při užití fancy spolu s příkazem \chapter{} je v tom, že se stránka s nadpisem kapitoly vysází s potlačenou sazbou záhlaví a zápatí. Je to poměrně logické — při knižní sazbě je toto chování v pořádku, horší to bývá právě u takovýchto krátkých textů, kde se autor (blázen 😉 ) rozhodl, že bude využívat členění na kapitoly. Proto je nutné spolu nepsat jen \chapter{}, ale \chapter{}\thispagestyle{fancy}, čímž potlačíte potlačení tisku záhlaví/zápatí — které se vysází. Původně jsem uvažoval i o použití služeb balíčku listings pro sazbu zdrojových kódů, ale protože takřka žádné v dokumentu nejsou, je balíček jen nadefinován v proj2.sty, ale není použit.

Nebudu zde opakovat pravidla sazby — napsal jsem poměrně obsáhlý seriál pro server LinuxEXPRES o programu LyX, který je WYSIWYM editorem založeném na LaTeXu, v rámci nějž se typografickými pravidly zabývám velmi do hloubky a velmi podrobně, doporučuji především matematický speciál.

Součástí hlavní části dokumentace je i seznam literatury. Ten jsem nechal generovat pomocí BibTeXu — geniálního nástroje. Nemusel jsem se tak starat o to, aby seznam literatury odpovídal české normě (ISO690 a ISO690-2) — BibTeX se o to postaral za mě. Odkazy jsem vypisoval ve tvaru (Příjmení, rok) a nebo Příjmení (rok), což prvně dovoluje norma a také se mi to líbí více (než [2] nebo [4]) . K tomu je zapotřebí balíček natbib a do preambule vložit ještě tyto dva řádky:

\bibliographystyle{abbrvnat}
\bibpunct{(}{)}{;}{a}{,}{,}

Samotná citace se poté provádí příkazy: citep{klic} a citet{klic}, které vypíší položku klic jako (Příjmení, rok) či Příjmení (rok).

Všechny obrázky jsou odkazovány nikoli s užitím příkazu \ref{}, ale \vref{}, který k odkazu automaticky řadí „na straně XX“ — což využívám, protože obrázky jsou v příloze — mnohdy o mnoho stran dále.

vref{} je ještě chytřejší. Pokud se odkaz nachází na téže straně, větu vynechává. Také případě +/-1 upravuje větu na „na předešlé/následující straně“. Bohužel není možné s ním pracovat správně spolu s rovnicemi, protože číslo rovnice se píše do závorek (i v případě odkazování). Takže pokud by se s rovnicí použil vref{}, byl by i text v závorce.

Obrázky — dodatky

Poslední části dominují obrázky. Všechny jsou ve floatech, připojeno několikrát přes subfloat — několik pod-floatů v jednom floatu. Ale postupně.

Grafy jsou vykreslovány v GNUPlotu. Z toho jsou exportovány do barevného PostScriptu a díky $ps2pdf převedeny do PDF. Easy 😉

Diagramy jsem kreslil pomocí programu Dia a vážení — peklo. V programu nebyl problém vykreslit všechno, co jsem chtěl — rozhodovací diagramy pro všechny algoritmy. Co ovšem problém již byl, bylo převedení formátu DIA do PDF. Já bych mnohdy při tvorbě diagramů potřeboval dynamickou velikost papíru (či možnost navolit si velikost tak, jak mi bude vyhovovat). Dia toto ovšem neumí a má natvrdo předdefinované velikosti. Při hodně „nudloidním“ či naopak čtvercovém tvaru grafu jste tak odsouzeni k tomu, že část „papíru“ bude zbytečně bílá či celý diagram bude zbytečně roztažený, aby „papír“ vyplnil celý.

Obrázek je vložen kódem:

\begin{figure}
\centerline{ \includegraphics[width=0.85\textwidth]{obrazek}  }
\caption{Popis obrazku}\label{klic_k_odkazovani}
\end{figure}

Je třeba dodržet pořadí \caption a až poté \label — tyto dvě se nesmí přehodit, jinak bude \ref{klic_o_odkazovani} směřovat s největší pravděpodobností úplně jinam (nejspíše na kapitolu/sekci/podsekci…, ve které je obrázek uveden, nikoli na obrázek samotný).

V úvodu jsem psal o subfloatech, tak ukáži, jak s nimi pracovat (jen náznak). Představme si, že máme jednu routinu, která může používat dvě subroutiny (podívejte se na stranu VII v dokumentaci). Chceme tedy, aby jako celek měl např. číslo 1, ale jednotlivé obrázky byly odvolatelné jako 1a, 1b či 1c.

\begin{figure}
\centering
\subfloat[Popisek prvního v hranatych zavorkach!!!]{
\includegraphics[width=0.4\textwidth]{obr1}
\label{klic_k_prvnimu} } %%pozor na složené závorky!!
\qquad
\subfloat[Popisek druheho]{
\includegraphics[width=0.4\textwidth]{obr2}
\label{klic_k_druhemu} }
\caption{Popisek pro oba obrazky}\label{klic_k_obema}
\end{figure}

V tomto příkladu budou vysázeny dva obrázky obr1 a obr2 vedle sebe s popisky (postupně) „Popisek prvního v hranatych zavorkach!!!“ a „Popisek druheho“, na které se bude volat příkazy \ref{klic_k_prvnimu} a nebo \ref{klic_k_druhemu}. Pokud byste rádi odkazovali na oba obrázky zaráz, použijete \ref{klic_k_obema}.
Takže Obrázek \ref{klic_k_obema} obsahuje dva pod-obrázky a to \ref{klic_k_prvnimu} a \ref{klic_k_druhemu} vysází: „Obrázek 1 obsahuje dva pod-obrázky a to 1a a 1b“.

A to je vše. Vše je vysázeno, hotovo. PDF dokument volně je ke stažení (případně je i přiložen k projektu číslo dvě IZP).

Napsat komentář

Vaše emailová adresa nebude zveřejněna. Vyžadované informace jsou označeny *