LaTeX/Listiranje izvornog koda

Korišćenje listings paketa

Korišćenjem listing paketa listings možemo ubaciti neformatiran tekst, kao kada bi koristili \begin{verbatim} ali njegov osnovni cilj je da obuhvati izvorni kod bilo kog programskog jezika u vašem dokumenu. Ako želite da obuhvatite pseudokodove ili algoritme, onda će Vam ovo Algorithms and Pseudocode biti korisno.

Da biste koristili paket, treba Vam:

\usepackage{listings}

listings paket podržava naglašavanja svih uobičajnih pogramskih jezika i veoma je prilagodljiv. Ako samo želite da pišete kod u okviru vašeg dokumenta paket pruža mogućnost lstlisting okruženja:

\begin{lstlisting} Put your code here. \end{lstlisting}

Još jedna mogućnost, koja je veoma korisna ako ste kreirali program na više fajlova i idalje radite na njemu, je da uvezete kod iz samog izvora. Na ovaj način, ako izmenite izvorni kod, treba samo da rekompajlujete LaTeX kod i vaš dokument će dobiti proširenje. Komanda je:

\lstinputlisting{source_filename.py}

u primeru je Python izvor, ali to nije bitno: možete ubaciti bilo koji fajl ali morate napisati puno ime fajla. Biće posmatran kao običan tekst i biće označen u skladu sa vašim podešavanjima, to znači da ne prepoznaje sam programski jezik. Vi možete precizirati, prilikom ubacivanja fajla o kom jeziku je reč na sledeći način:

\lstinputlisting[language=Python]{source_filename.py}

Možete precizirati i veličine za fajl.

\lstinputlisting[language=Python, firstline=37, lastline=45]{source_filename.py}

Ovo je korisno ako ste sigurni da se fajl neće menjati (barem do te određene linije). Možete takođe izostaviti firstline ili lastline parametar: što znači sve do ili počevši od ove tačke.

Ovo je elementarni primer koda u Paskalu:

\documentclass{article}
\usepackage{listings}             % Убацује listings-package
\begin{document}
\lstset{language=Pascal}          % Поставите жељени језик (можете га мењати за сваки блок кода)

\begin{lstlisting}[frame=single]  % Почните блок кода
for i:=maxint to 0 do
begin
{ do nothing }
end;
Write('Case insensitive ');
Write('Pascal keywords.');
\end{lstlisting}

\end{document}

Podržani jezici

Podržava sledeće programske jezike:

ABAP^2,4, ACSL, Ada⁴, Algol⁴, Ant, Assembler^2,4, Awk⁴, bash, Basic^2,4, C#⁵, C++⁴, C⁴, Caml⁴, Clean, Cobol⁴, Comal, csh, Delphi, Eiffel, Elan, erlang, Euphoria, Fortran⁴, GCL, Gnuplot, Haskell, HTML, IDL⁴, inform, Java⁴, JVMIS, ksh, Lisp⁴, Logo, Lua², make⁴, Mathematica^1,4, Matlab, Mercury, MetaPost, Miranda, Mizar, ML, Modelica³, Modula-2, MuPAD, NASTRAN, Oberon-2, Objective C⁵ , OCL⁴, Octave, Oz, Pascal⁴, Perl, PHP, PL/I, Plasm, POV, Prolog, Promela, Python, R, Reduce, Rexx, RSL, Ruby, S⁴, SAS, Scilab, sh, SHELXL, Simula⁴, SQL, tcl⁴, TeX⁴, VBScript, Verilog, VHDL⁴, VRML⁴, XML, XSLT.

Za neke od njih, nekoliko dijalekata je podržano. Za više informacija, pogledajte u dokumentaciji koja dolazi sa paketom, trebalo bi da bude u Vašoj distribuciji pod imenom listings-*.dvi.

Beleške

1. Podržava Mathematica kod samo ako pišete u običnom tekst formatu. Ne možete ubaciti *.NB files \lstinputlisting{...} kako je moglo sa bilo kojim drugim programskim jezikom, ali Mathematica može da izveze kao pretty-formatted LaTeX izvor.
2. Specifikacija dijalekta je obavezna za ove jezike (e.g. language={[x86masm]Assembler}).
3. Modelica je podržana preko dtsyntax paketa dostupnog na here.
4. Za ove jezike, više dijalekata je podržano. C, na primer, koristi ANSI, Handel, Objective i Sharp. Pogledajte stanu 12 listings manual.
5. Definiše se kao dijalekat drugog jezika

Podešavanja

Možete modifikovati nekoliko parametara koji će uticati na izgled koda. Možete staviti sledeći kod bilo gde u dokument (nije važno da li pre ili posle \begin{document}),promenite ga u skladu sa vašim potrebama. Značenje je objašnjeno pored svake linije.

\usepackage{listings}
\usepackage{color}

\definecolor{mygreen}{rgb}{0,0.6,0}
\definecolor{mygray}{rgb}{0.5,0.5,0.5}
\definecolor{mymauve}{rgb}{0.58,0,0.82}

\lstset{ %
  backgroundcolor=\color{white},   % одаберите боју позадине; морате додати \usepackage{color} or \usepackage{xcolor}
  basicstyle=\footnotesize,        % величина фонта који се користи у коду
  breakatwhitespace=false,         % поставља да ли ће се аутоматски прекиди дешавати код whitespace-а
  breaklines=true,                 % поставља аутоматски прекид линије
  captionpos=b,                    % поставља caption-position на дно
  commentstyle=\color{mygreen},    % стил коментара
  deletekeywords={...},            % ако желите да избришете кључне речи из језика
  escapeinside={\%*}{*)},          % ако желите да убаците LaTeX у Ваш код
  extendedchars=true,              % допушта Вам да користите non-ASCII characters;само за 8-битно кодирање, не ради са UTF-8
  frame=single,	                   % додаје оквир око кода
  keepspaces=true,                 % задржава размаке у тексту, корисно за одржавање увлачења у коду (можда ће требати columns=flexible)
  keywordstyle=\color{blue},       % стил кључне речи
  language=Octave,                 % језик кода
  otherkeywords={*,...},           % ако желите додати више кључних речи 
  numbers=left,                    % где да поставља бројеве линија; могуће вредности су (none, left, right)
  numbersep=5pt,                   % колико далеко су бројеви линија од кода
  numberstyle=\tiny\color{mygray}, % стил који се користи за линије кода
  rulecolor=\color{black},         % ако није постављено, боја оквира се може променити на прекидима линија у не-црном тексту (на пример cкоментари (овде зеленом))
  showspaces=false,                % приказује свуда размаке додајући специфичне доње црте што поништава 'showstringspaces'
  showstringspaces=false,          % доње црте само на стринговима
  showtabs=false,                  % приказује табове на стринговима додајући специфичне доње црте
  stepnumber=2,                    % размак између две линије-броја. Ако је 1 , свака линија ће бити нумерисана
  stringstyle=\color{mymauve},     % дослован стил стринга
  tabsize=2,	                   % поставља примаран размак таба на 2 размака
  title=\lstname                   % показује име фајла од фајлова садржаних у\lstinputlisting; такође покушајте caption уместо title
}

escapeinside

escapeinside liniju treba objasniti. Opcija escapeinside={A}{B} će određivati razdvojnike za odlaženje u LaTeX kod , tojest sav kod između "A" i "B" biće raščlanjen kao LaTeX preko trenutnog stila listiranja . U primeru gore, komentari za Octave počinju sa %, i biće štampani u dokumentu osim ako ne počinju sa %*, u tom slučaju se čitaju kao LaTeX (sa svim zadovoljenim LaTeX komandama) sve dok se ponovo ne zatvore sa *). Ako dodate gornji paragraf, sledeće se može koristi za izmenu podešavanja u kodu:

\lstset{language=C,caption={Descriptive Caption Text},label=DescriptiveLabel}

Postoji još dosta opcija, pogledajte zvaničnu dokumentaciju.

Definisanje stila

Paket Vam dopušta da definišete stil, tojest profile koji određuju set podešavanja.

Primer

\lstdefinestyle{customc}{
  belowcaptionskip=1\baselineskip,
  breaklines=true,
  frame=L,
  xleftmargin=\parindent,
  language=C,
  showstringspaces=false,
  basicstyle=\footnotesize\ttfamily,
  keywordstyle=\bfseries\color{green!40!black},
  commentstyle=\itshape\color{purple!40!black},
  identifierstyle=\color{blue},
  stringstyle=\color{orange},
}

\lstdefinestyle{customasm}{
  belowcaptionskip=1\baselineskip,
  frame=L,
  xleftmargin=\parindent,
  language=[x86masm]Assembler,
  basicstyle=\footnotesize\ttfamily,
  commentstyle=\itshape\color{purple!40!black},
}

\lstset{escapechar=@,style=customc}

U našem primeru, postavljamo samo dve opcije globalno: zadani stil i karakter za izlaz. Korišćenje:

\begin{lstlisting}
#include <stdio.h>
#define N 10
/* Block
 * comment */

int main()
{
    int i;

    // Line comment.
    puts("Hello world!");
    
    for (i = 0; i < N; i++)
    {
        puts("LaTeX is also great for programmers!");
    }

    return 0;
}
\end{lstlisting}

\lstinputlisting[caption=Scheduler, style=customc]{hello.c}

C deo će se štampati kao

Automatsko uključenje fajla

Ako imate dosta izvornih fajlova koje biste želeli ubaciti, možda Vam bude korisno da ponavljate istu stvar više puta. Ovde macros pokazuju svoju pravu moć.

\newcommand{\includecode}[2][c]{\lstinputlisting[caption=#2, escapechar=, style=custom#1]{#2}<!---->}
% ...

\includecode{sched.c}
\includecode[asm]{sched.s}
% ...

\lstlistoflistings

u ovom primeru, pravimo jednu komandu da olakšamo inkluziju izvornog koda. Postavljamo zadanu vrednost na customc. Svo listiranje i ime kao caption: ne moramo da pišemo ime fajla dva puta zahvaljujući macro. Konačno sve listings nabrajamo sa ovom komandom iz listings paketa.

Pogledajte Macros za više detalja.

Problemi kodiranja

Po zadanoj vrednosti,listings ne podržava multi-byte kodiranje izvornog koda. extendedchar opcija radi samo za 8-bitno kodiranje kao što je latin1.

Za rad sa UTF-8, treba da kažete listings kako da tumači specijalne karaktere definišući ih na sledeći način

\lstset{literate=
  {á}{{\'a}}1 {é}{{\'e}}1 {í}{{\'i}}1 {ó}{{\'o}}1 {ú}{{\'u}}1
  {Á}{{\'A}}1 {É}{{\'E}}1 {Í}{{\'I}}1 {Ó}{{\'O}}1 {Ú}{{\'U}}1
  {à}{{\`a}}1 {è}{{\`e}}1 {ì}{{\`i}}1 {ò}{{\`o}}1 {ù}{{\`u}}1
  {À}{{\`A}}1 {È}{{\'E}}1 {Ì}{{\`I}}1 {Ò}{{\`O}}1 {Ù}{{\`U}}1
  {ä}{{\"a}}1 {ë}{{\"e}}1 {ï}{{\"i}}1 {ö}{{\"o}}1 {ü}{{\"u}}1
  {Ä}{{\"A}}1 {Ë}{{\"E}}1 {Ï}{{\"I}}1 {Ö}{{\"O}}1 {Ü}{{\"U}}1
  {â}{{\^a}}1 {ê}{{\^e}}1 {î}{{\^i}}1 {ô}{{\^o}}1 {û}{{\^u}}1
  {Â}{{\^A}}1 {Ê}{{\^E}}1 {Î}{{\^I}}1 {Ô}{{\^O}}1 {Û}{{\^U}}1
  {œ}{{\oe}}1 {Œ}{{\OE}}1 {æ}{{\ae}}1 {Æ}{{\AE}}1 {ß}{{\ss}}1
  {ű}{{\H{u}}}1 {Ű}{{\H{U}}}1 {ő}{{\H{o}}}1 {Ő}{{\H{O}}}1
  {ç}{{\c c}}1 {Ç}{{\c C}}1 {ø}{{\o}}1 {å}{{\r a}}1 {Å}{{\r A}}1
  {€}{{\EUR}}1 {£}{{\pounds}}1
}

Gornja tabela pokriva skoro sve znakove latinice. Za detaljnija objašnjenja Korišćenja literate opcije pogledajte odeljak 6.4 u Listings Documentation.

Još jedna mogućnost je da zamenite \usepackage{listings} (u preambuli) sa \usepackage{listingsutf8}.

Prilagođavanje naslova

Možete podesiti raznovrsne naslove za Vaše listiranje koristeći caption paket. Evo primera za listings.

\usepackage{caption}
\usepackage{listings}

\DeclareCaptionFont{white}{ \color{white} }
\DeclareCaptionFormat{listing}{
  \colorbox[cmyk]{0.43, 0.35, 0.35,0.01 }{
    \parbox{\textwidth}{\hspace{15pt}#1#2#3}
  }
}
\captionsetup[lstlisting]{ format=listing, labelfont=white, textfont=white, singlelinecheck=false, margin=0pt, font={bf,footnotesize} }

% ...

\lstinputlisting[caption=My caption]{sourcefile.lang}

Paket minted

minted je alternativa za listings koji je postao popularan. Koristi ekternu Python biblioteku Pygments za hajlajtovanje koda, koja od novembra 2014. pruža više od 300 podržanih jezika i tekstualnih formata.

Kako se paket oslanja na eksternu Python biblioteku, podešavanje zahteva nešto više koraka nego LaTeX paket, zato Vas molimo da pogledate njihovu stranicu GitHub repo i njihov priručnik.

Reference

Dosta više detaljnih informacija možete pronaći na PDF by Carsten Heinz and Brooks Moses.

Detalji i dokumentacija o Listings paketu mogu se pronaći na its CTAN website.