LaTeX/Листирање изворног кода

Коришћење listings пакета

Коришћењем листинг пакета listings можемо убацити неформатиран текст, као када би користили \begin{verbatim} али његов основни циљ је да обухвати изворни код било ког програмског језика у вашем докумену. Ако желите да обухватите псеудокодове или алгоритме, онда ће Вам ово Algorithms and Pseudocode бити корисно.

Да бисте користили пакет, треба Вам:

\usepackage{listings}

listings пакет подржава наглашавања свих уобичајних пограмских језика и веома је прилагодљив. Ако само желите да пишете код у оквиру вашег документа пакет пружа могућност lstlisting окружења:

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

Још једна могућност, која је веома корисна ако сте креирали програм на више фајлова и идаље радите на њему, је да увезете код из самог извора. На овај начин, ако измените изворни код, треба само да рекомпајлујете LaTeX код и ваш документ ће добити проширење. Команда је:

\lstinputlisting{source_filename.py}

у примеру је Python извор, али то није битно: можете убацити било који фајл али морате написати пуно име фајла. Биће посматран као обичан текст и биће означен у складу са вашим подешавањима, то значи да не препознаје сам програмски језик. Ви можете прецизирати, приликом убацивања фајла о ком језику је реч на следећи начин:

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

Можете прецизирати и величине за фајл.

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

Ово је корисно ако сте сигурни да се фајл неће мењати (барем до те одређене линије). Можете такође изоставити firstline или lastline параметар: што значи све до или почевши од ове тачке.

Ово је елементарни пример кода у Паскалу:

\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}

Подржани језици

Подржава следеће програмске језике:

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.

За неке од њих, неколико дијалеката је подржано. За више информација, погледајте у документацији која долази са пакетом, требало би да буде у Вашој дистрибуцији под именом listings-*.dvi.

Белешке

1. Подржава Mathematica код само ако пишете у обичном текст формату. Не можете убацити *.NB files \lstinputlisting{...} како је могло са било којим другим програмским језиком, али Mathematica може да извезе као pretty-formatted LaTeX извор.
2. Спецификација дијалекта је обавезна за ове језике (e.g. language={[x86masm]Assembler}).
3. Modelica је подржана преко dtsyntax пакета доступног на here.
4. За ове језике, више дијалеката је подржано. C, на пример, користи ANSI, Handel, Objective и Sharp. Погледајте стану 12 listings manual.
5. Дефинише се као дијалекат другог језика

Подешавања

Можете модификовати неколико параметара који ће утицати на изглед кода. Можете ставити следећи код било где у документ (није важно да ли пре или после \begin{document}),промените га у складу са вашим потребама. Значење је објашњено поред сваке линије.

\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 линију треба објаснити. Опција escapeinside={A}{B} ће одређивати раздвојнике за одлажење у LaTeX код , тојест сав код између "A" и "B" биће рашчлањен као LaTeX преко тренутног стила листирања . У примеру горе, коментари за Octave почињу са %, и биће штампани у документу осим ако не почињу са %*, у том случају се читају као LaTeX (са свим задовољеним LaTeX командама) све док се поново не затворе са *). Ако додате горњи параграф, следеће се може користи за измену подешавања у коду:

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

Постоји још доста опција, погледајте званичну документацију.

Дефинисање стила

Пакет Вам допушта да дефинишете стил, тојест профиле који одређују сет подешавања.

Пример

\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}

У нашем примеру, постављамо само две опције глобално: задани стил и карактер за излаз. Коришћење:

\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 део ће се штампати као

Аутоматско укључење фајла

Ако имате доста изворних фајлова које бисте желели убацити, можда Вам буде корисно да понављате исту ствар више пута. Овде macros показују своју праву моћ.

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

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

\lstlistoflistings

у овом примеру, правимо једну команду да олакшамо инклузију изворног кода. Постављамо задану вредност на customc. Сво листирање и име као caption: не морамо да пишемо име фајла два пута захваљујући macro. Коначно све listings набрајамо са овом командом из listings пакета.

Погледајте Macros за више детаља.

Проблеми кодирања

По заданој вредности,listings не подржава multi-byte кодирање изворног кода. extendedchar опција ради само за 8-битно кодирање кao што је latin1.

За рад са UTF-8, треба да кажете listings како да тумачи специјалне карактере дефинишући их на следећи начин

\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
}

Горња табела покрива скоро све знакове латинице. За детаљнија објашњења Коришћења literate опције погледајте одељак 6.4 у Listings Documentation.

Још једна могућност је да замените \usepackage{listings} (у преамбули) са \usepackage{listingsutf8}.

Прилагођавање наслова

Можете подесити разноврсне наслове за Ваше листирање користећи caption пакет. Ево примера за 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}

Пакет minted

minted је алтернатива за listings који је постао популаран. Користи ектерну Python библиотеку Pygments за хајлајтовање кода, која од новембра 2014. пружа више од 300 подржаних језика и текстуалних формата.

Како се пакет ослања на екстерну Python библиотеку, подешавање захтева нешто више корака него LaTeX пакет, зато Вас молимо да погледате њихову страницу GitHub repo и њихов приручник.

Референце

Доста више детаљних информација можете пронаћи на PDF by Carsten Heinz and Brooks Moses.

Детаљи и документација о Listings пакету могу се пронаћи на its CTAN website.