LATEX sazba zdrojového kódu

ČESKÉ VYSOKÉ UČENÍ TECHNICKÉ V PRAZE FAKULTA STAVEBNÍ OBOR GEODÉZIE A KARTOGRAFIE KATEDRA MAPOVÁNÍ A KARTOGRAFIE LATEX sazba zdrojového kódu semestrální práce Anna Kratochvílová V Praze dne 26. 4. 2011 Kartografická polygrafie a reprografie

Úvod Sazba zdrojového kódu je věc potřebná a není úplně jednoduché vysázet jej tak, aby to odpovídalo konvencím daného programovacího jazyka a aby byl kód srozumitelný. Navíc často je potřeba jej prezentovat a zde hraje roli i estetické působení. Co vlastně znamená sazba zdrojového kódu? Především zachovává speciální znaky a odsazení. Typicky se pro zdrojový kód používá jiné písmo než pro zbytek textu, a to především písmo bezproporční (strojopis). V literatuře se lze setkat i s použitím kurzívy. Dalšími požadavky může být zvýraznění klíčových slov, číslování řádků či jejich zalomení. Záleží na konkrétních potřebách a vkusu, nicméně systém L A TEX umožňuje splnit i náročné požadavky na sazbu zdrojového kódu. 1 Sazba zdrojového kódu v dokumentu Následující text shrnuje nejpoužívanější způsoby sazby, nicméně je třeba zdůraznit, že v této oblasti neustále dochází k vývoji a nové možnosti stále přibývají. 1.1 Příkaz verb a prostředí verbatim Jednou z nejjednodušších možností, jak vysázet zdrojový kód bezrozměrným fontem včetně speciálních znaků, je použít příkaz \verb či prostředí verbatim. První možnost je vhodná pro kratší úryvky na řádku, druhá varianta slouží pro bloky zdrojového kódu. Po příkazu \verb následuje oddělovač, kterým může být jakýkoli speciální znak (kromě mezery a *). Příkaz platí pro následující text, dokud nenarazí na zvolený oddělovač. Například \verb mezer, kolik chcete vytiskne toto: mezer, kolik chcete. Prostředí verbatim funguje stejně jako jiná prostředí. Následuje příkaz a jeho výsledek: \ begin { verbatim } zde se \ textit { prikazy } neinterpretuji \ end { verbatim } zde se \textit{prikazy} neinterpretuji Alternativou k prostředí verbatim je prostředí alltt, pro jeho použití je nutný stejnojmenný balíček. Výhodou je to, že se uvnitř tohoto prostředí interpretují příkazy L A TEXu. Předchozí příklad by tak měl následující výstup: zde se prikazy neinterpretuji Je třeba dodat, že ve zmiňovaných příkazech a prostředích nejsou s češtinou žádné komplikace. Pokud v ukázkových textech chybí diakritika, má to svůj důvod, je zde totiž použit balíček Listings, u kterého je použití diakritiky problematické. Na druhou stranu, psát zdrojový kód v češtině se stejně nedoporučuje. 1

1.2 Balíček Listings Listings je jedním z nejpoužívanějších balíčků pro sázení zdrojového kódu. Mezi jeho největší výhody patří to, že vzhled výpisů kódu si lze jednoduše přizpůsobit vlastním potřebám. Podporuje přes 70 programovacích jazyků a u některých i více dialektů. To umožňuje uživateli nastavit odlišný vzhled pro klíčová slova, komentáře a řetězce. Dále si lze vybrat, jakou formou kód vkládat. Lze vložit útržky kódu přímo do textu či na samostatný řádek, načíst kód ze souboru a případně použít plovoucí prostředí s popiskem a číslováním. Vzhled výpisu kódu je možné zvýraznit rámečkem a odlišnou barvou pozadí. Samozřejmostí je číslování řádků s možností se na ně v textu odkázat. Možnosti nastavení jsou popsány dále v textu. Pro použití balíčku je třeba jej uvést v preambuli (tj. mezi \documentclass a \begin {document}): \ usepackage { listings } 1.2.1 Vkládání kódu Vložit zdrojový kód do textu lze několika způsoby. Pro krátký útržek kódu je často vhodné jej umístit přímo do textu. K tomu slouží příkaz \lstinline, za kterým následuje kód v oddělovačích, které lze libovolně zvolit tak, aby se vybrané znaky nevyskytovaly v kódu. Takže funguje \lstinline int i; i++, ale třeba i \lstinline*int i; i++*, což obojí produkuje: int i; i++. Další možností je vkládat kód mimo text, což zajišt uje prostředí lstlisting: \ begin { lstlisting } int i = 100; i ++; std :: cout << i << std :: endl ; Pokud chcete vložit větší část kódu, lze jej načíst přímo ze souboru. To má mimo jiné výhodu, že při změně v programu stačí pouze přeložit soubor v L A TEXu a není tak třeba změnu přepisovat na více místech. Příkaz \ lstinputlisting [ firstline =24, lastline =33]{ semestr. sty } vypíše následující část kódu (kód v L A TEXu): \ def \ @makechapterhead #1{ % \ vspace *{50\ p@}% {\ parindent \ z@ \ raggedright \ normalfont \ ifnum \ c@ secnumdepth >\ m@ ne \ Large \ bfseries \ thechapter. \ space \fi \ interlinepenalty \@M \ Large \ bfseries #1\ par \ nobreak \ vskip 40\ p@ Za povšimnutí stojí parametry firstline a lastline, kterými lze omezit rozsah vypisovaného kódu. 2

Pro výpisy kódu může být výhodné je umístit do číslovaného plovoucího prostředí se značkou (label) a popiskem, což se zařídí přidáním následujících nepovinných parametrů k předcházejícím příkazům. Na ukázku kódu se pak můžete odvolávat standardně přes \ref{klic} a \pageref{klic}, tedy např. jako na uvedenou ukázku č. 1. \ begin { lstlisting }[ float =h, caption = Float prostredi, label = klic ] void nicnedelam (); void nicnedelam (); Ukázka kódu 1: Float prostředí Na doplnění informací je vhodné uvést, že příkazy caption a label lze uvést i bez plovoucího prostředí. Pro dokumenty v češtině se hodí předefinovat anglické označení Listing pomocí \renewcommand{\lstlistingname}{ukázka kódu}. 1.2.2 Možnosti nastavení a jejich význam K nastavení parametrů slouží příkaz \lstset{parametr=hodnota parametru}. Do příkazu lze napsat libovolný počet parametrů oddělenými čárkou. Pokud takto cokoliv nastavíme, má pak toto nastavení platnost pro celý dokument. Nastavíme-li je však přímo při vkládání kódu (jako nepovinné parametry v hranatých závorkách), platí nastavení pouze pro tu konkrétní ukázku kódu. Jestliže potřebujeme v dokumentu střídat různá nastavení, je výhodné nastavit styly pomocí \lstdefinestyle, které pak použijeme při vkládání kódu. Následující výčet v tabulce č. 1 na straně 4 nepokrývá zdaleka všechny možnosti nastavení, vybírá jen ty základní. 1.2.3 Vzhled a zvýraznění ukázek kódu Když chceme zvýraznit kód, pomůže nám nastavení frame a backgroundcolor. Při použití barev nezapomeňte vložit balíček color pomocí \usepackage{color} s možností nepovinných parametrů usenames, dvipsnames v hranatých závorkách. Výsledky různých nastavení zmíněných parametrů jsou na obrázku č. 1 na straně 4: 3

Parametr Příklad hodnoty Popis language C++, Python,... nastavuje podporu pro určitý programovací jazyk basicstyle \small\ttfamily základní vzhled písma commentstyle \itshape vzhled komentářů keywordstyle \color{red} vzhled klíčových slov morekeywords {some, key, words} přidání klíčových slov style mystyle použití uživatelem předdefinovaného stylu showspaces true, false vkládá viditelné mezery numbers none, left, right číslování řádků numberstyle \tiny vzhled čísel řádků stepnumber {1, 2,...} číslovaný je každý n-tý řádek numbersep 10pt, 2mm vzdálenost číslování od kódu caption popisek popisek ukázky kódu captionpos t, b umístění popisku title \lstname nečíslovaný popisek, například název vkládaného souboru breaklines true, false zalomení řádků breakatwhitespace true, false zalomení řádku v bílých znacích breakindent 20em, 40mm odsazení řádku po zalomení breakautoindent true, false automatické odsazení zalomeného řádku gobble 1, 2, 3,... ignoruje daný počet znaků od začátku řádku escapeinside {\%*}{*} text mezi zvolenými znaky není ve výpisu, možné vložit \label pro odkazování se na konkrétní řádku Tab. 1: Možnosti nastavení \ begin { lstlisting }[ frame = shadowbox, rulesepcolor =\ color { Gray }]... \ definecolor { lightgrey }{ RGB }{250,250,250} \ begin { lstlisting }[ frame =LBtr, backgroundcolor =\ color { lightgrey }, frameround = tttt ]... \ begin { lstlisting }[ frame = lines, framerule =2pt, rulecolor =\ color { BurntOrange }, backgroundcolor =\ color { Goldenrod }]... Obr. 1: Ukázka rámečků 4

1.2.4 Ukázka použití Pro lepší představu je zde ukázáno jedno z vhodných nastavení balíčku (ukázka č. 2) a odpovídající výsledek (ukázka č. 3 na straně 6). Ukázka kódu 2: Ukázka nastavení pro kód v C++ \ lstinputlisting [ float =ht, caption = Ukazka kodu v C++, language =C++, basicstyle =\ ttfamily \ small \ color { black }, commentstyle =\ itshape, keywordstyle =\ color { Blue }, showstringspaces = false, frame = lines, backgroundcolor =\ color { lightgrey }, numbers = left, numberstyle =\ small, stepnumber =5, framexleftmargin =10 mm, xleftmargin =10 mm, breakindent =20 em, breakatwhitespace = true, breaklines = true ] { polygon.h} 2 Zdrojové kódy v prezentaci L A TEX Beamer V prezentacích třídy Beamer lze pro sazbu zdrojových kódu víceméně používat stejné prostředky jako v normálním dokumentu L A TEXu. Navíc však lze prezentování kódu ozvláštnit různým skrýváním a zvýrazňováním určité části kódu. 2.1 Vložení zdrojového kódu Kód lze v prezentaci zobrazit několika způsoby, některé z nich již byly popsány v předchozích částech. V každém případě je nutné přidat podmínku [fragile] ve tvaru \begin {frame}[fragile], bez které se žádný z následujících způsobů neobejde. Kód lze vložit: přímo do řádku: \verb zdrojovy kod samostatně na více řádků: \ begin { verbatim }... \ end { verbatim } samostatně na více řádků, znaky \, {, } jsou vyhodnoceny, což umožňuje používat příkazy pro skrývání a zvýraznění přímo ve zdrojovém kódu: \ begin { semiverbatim } \ alert { zvyrazneny kod } \ end { semiverbatim } použitím balíčku Listings. 2.2 Skrývání a zvýraznění kódu Pokud chceme mít prezentaci zdrojového kódu zajímavější, lze toho dosáhnout postupným odkrýváním a zakrýváním určitých částí kódu s jejich případným barevným zvýrazněním. Pro účely odkrývání a zakrývání lze použít příkaz \uncover se specifikací, kdy se má daný řádek kódu zviditelnit. Specifikace <1-3,5-> například znamená, že kód 5

Ukázka kódu 3: Ukázka výsledku nastavení class Polygon { protected : std :: vector < Point > points ; 5 public : Polygon () {} void add ( const Point &p) { points. push_back (p); } const Point & getpoint ( unsigned int index ) const { return points [ index ]; } const Point & operator []( int index ) const { return points [ index ]; } 10 unsigned int size () const { return points. size (); } /** Returns number of points in polygon with the last point * which is the same as the first point. */ unsigned int getsize () const { return size (); } 15 void clear () { points. clear (); } bool isvalid () { unsigned int size = points. size (); if ( size > 0) 20 { for ( unsigned int i = 0; i < size ; i ++) { if (! points.at(i). isvalid ()) return false ; } if ( points [0] == points [size -1]) 25 return true ; } else return false ; } bude viditelný na prvním až třetím slidu, pak zmizí a objeví se až na pátém a už tak zůstane. Podobně se chová příkaz \alert, který kód zvýrazní červenou barvou (lze nastavit i jinou). Postup je uveden v následujícím příkladě č. 4 na straně 4, nicméně účinek nastavení je patrný až v prezentaci. 6

Ukázka kódu 4: Postupné zobrazení kódu v prezentaci \ begin { frame }[ fragile ] \ frametitle { Postupne zobrazeni kodu \ ldots } \ begin { semiverbatim } \ uncover <3 - >{\ alert <3 >{ SELECT gid, ST_ BuildArea (ST_ Collect ( way )) AS way }} \ uncover <3 - >{ \ alert <3 >{ FROM }} \ uncover <3 - >{ \ alert <3 >{(}}\ uncover <2 - >{\ alert <2 >{ SELECT }} \ uncover <2 - >{ \ alert <2 >{ gid,}} \ uncover <2 - >{ \ alert <2 >{ ST_ BuildArea (ST_ Union ( ring.way, ST_ StartPoint ( ring. way )))}} \ uncover <2 - >{ \ alert <2 >{ AS way }} \ uncover <2 - >{ \ alert <2 >{ FROM }} \ uncover <2 - >{ \ alert <2 >{(}}\ uncover <1 - >{\ alert <1 >{ SELECT DISTINCT }} \ uncover <1 - >{ \ alert <1 >{ gid,}} \ uncover <1 - >{ \ alert <1 >{ ST_ ExteriorRing (( ST_ DumpRings ( way )). geom ) AS way }} \ uncover <1 - >{ \ alert <1 >{ FROM f 10. lesni _ porosty }} \ uncover <1 - >{ \ alert <1 >{ WHERE NOT ST_ IsValid ( way ) }}\ uncover <2 - >{\ alert <2 >{) }} \ uncover <2 - >{ \ alert <2 >{ AS ring }}\ uncover <3 - >{)} \ uncover <3 - >{ \ alert <3 >{ AS after _ union }} \ uncover <3 - >{\ alert <3 >{ GROUP BY gid ;}} \ end { semiverbatim } \ end { frame } 7

Závěr Kromě výše zmiňovaných možností sazby zdrojového kódu existují i další, se kterými ale nemám osobní zkušenost, nicméně na internetu lze v této oblasti dohledat mnoho návodů a rad. Pokud autor programu potřebuje předvést výsledky své práce v dokumentu nebo v prezentaci, měl by se rozhodně seznámit s uvedenými možnostmi a zvolit si tu vhodnou. Čas tomu věnovaný se mu určitě vyplatí. Literatura [1] LaTeX. Wikibooks, open books for an open world [online]. 19 January 2005, last modified on 6 April 2011 [cit. 2011-04-06]. URL: http://en.wikibooks.org/wiki/latex/ [2] Heinz, Carsten; Moses, Brooks. The Listings Package [online], [cit. 2011-04-06], URL: http://mirrors.ctan.org/macros/latex/contrib/listings/listings.pdf [3] Tantau, Till; Wright, Joseph; Miletić, Vedran. The beamer class: User Guide for version 3.10., [online], [cit. 2011-04-06], URL: http://ftp.cstug.cz/pub/tex/ctan/macros/ latex/contrib/beamer/doc/beameruserguide.pdf 8