Как оформить исходный код программ в LaTeX без адских страданий

Иногда в документ LaTeX нужно вставить кусок программного кода или псевдокод, поясняющий алгоритм. В зависимости от языка программирования и целей, подсветка кода в LaTeX достигается подключаемыми пакетами расширений разной степени кривизны и безумия документации.

Пост подвергался чистке и правке после публикации:
Автор заходил править этот пост 16 августа 2013 года.

Как просто вставить программный код в LaTeX без боли и страданий?
Именно такой вопрос однажды получил автор этих строк в свой ящик электропочты. Ответ: если хочется quick-and-dirty решения, можно воспользоваться пакетом verbatim, который запрещает LaTeX обрабатывать вставленный код и просто отображает код как есть.  Дёшево и сердито:

\begin{verbatim}
int main(void)
{
int i, j;

for (i=0; i<3; ++i) {
for (j=0; j<3; ++j) printf("%5.1f", m[i*3+j]);
putchar('\n');
}

cblas_dgemv(CblasRowMajor, CblasNoTrans, 3, 3, 1.0, m, 3, x, 1, 0.0, y, 1);


for (i=0; i<3; ++i) printf("%5.1f\n", y[i]);

return 0;
}
\end{verbatim}

Перед вставкой можно сделать так:

cat -n code.c | fold -w 60

Такая комбинация берёт исходный код в файле code.c и расставляет номера строк (ключ -n), перенося длинные строки (ключ -w 60 для ширины в 60 символов). Вот как это будет выглядеть в итоге:

Просто, дёшево, сердито и безболезненно.


Verbatim с оформлением - alltt
Ещё есть пакет под звучным названием alltt, который добавляет окружение alltt - это тот же verbatim, только в нём доступно оформление  цветом, полужирным и т.д. Вот пример:

 А вот для него код:

\documentclass[a4paper,10pt]{article}

\usepackage[T2A]{fontenc}
\usepackage[koi8-r]{inputenc}

\usepackage[usenames,dvipsnames]{color}

\usepackage{alltt}

\begin{document}

\section{C code via alltt}
\begin{alltt}
     \textit{1   int main(void)}
     2  {
     3    int i, j;
     4
     5    for (i=0; i<3; ++i) {
     6      for (j=0; j<3; ++j) printf("%5.1f", m[i*3+j]);
     7      putchar('\\n');
     8    }
     9
    10    cblas_dgemv(CblasRowMajor, CblasNoTrans, 3, 3, 1.0
, m, 3, x, 1, 0.0, y, 1);
    11
    12
    14
    15    return 0;
    16  }
\end{alltt}


\end{document} 

Нюанс: в alltt eсть проблема c экранированием специальных символов типа \ и { поскольку alltt начинает воспринимать их как элементы оформления. Документация состоит из двух страниц.



Как оформить псевдокод в LaTeX?
Часто приводить дословно  исходный код программы не требуется, но нужно пояснить общий ход алгоритма псевдокодом. Для оформления псевдокодов и алгоритмов наиболее вменяемый пакет называется algorithm2e доступный отсюда.

Скачиваем стилевой файл algorithm2e.sty и прописываем его в преамбуле документа:

\usepackage[linesnumbered,boxed]{algorithm2e}

Здесь я включил следующие полезные параметры:

• linesnumbered - включает нумерацию строк в алгоритме.
• boxed - рисует рамку вокруг алгоритма.

Про остальные параметры можно узнать из отличной документации algorithm2e.pdf в разделе 6 The options of the package.

Вот как выглядит алгоритм, оформленный пакетом algorithm2e::

А вот для него код с комментариями (здесь комментарии, показанные серым цветом - для латеха и они не будут видны в алгоритме,  а комментарии с двойной косой чертой - для показа в алгоритме):

\begin{algorithm}[H]
\SetAlgoLined %% Это соединяет линиями логические части
%% алгоритма типа if-then-else

\KwData{ experiment.data} %% здесь можно указать исходные параметры

\KwResult{ output, xoptimal } %% результат работы программы

x=0;

\While{ $\tau_{norm} > \varepsilon_{tol}$ }{

$s_{k-1} \leftarrow x_k - x_{k-1}$;

// Step lenght computation: %% это комментарий, который будет виден.

\eIf{$k$ is even}{
$ \alpha_k^{ABB} = \frac{ s_{k-1}^T y_{k-1}}{y_{k-1}^T y_{k-1}}$
}{ %% ELSE
$\alpha_k^{ABB} = \frac{ s_{k-1}^T s_{k-1}}{s_{k-1}^T y_{k-1}}$
} %% END \eIf{$k$ is even}{

$k \leftarrow k + 1$;

\For{ i = 1}{
$x_{i+1} = P_\Omega(x_i - \alpha_k^{ABB}*g_k)$;

} %% END \For{ i = 1}{

// Compute the termination constant %% это комментарий, который будет виден.

$\tau_{norm} = abs ( \,\,\, ||x_{k}||_2 - ||x_{k-1}||_2 \,)$

} %% END \While{ $\tau_{norm} > \varepsilon_{tol}$ }{

\caption{Pseudo-code for basic algorithm.}
\label{alg:generalGP}
\end{algorithm}

На алгоритм можно ссылаться, как и на другие объекты в ЛаТеХе -  пакет algorithm2e поддерживает ссылки обычной командой \label{alg:generalGP} и соответственно ссылкой \ref{alg:generalGP}.

Стоит отметить на удивление хорошую документацию: в справочном файле algorithm2e.pdf есть всё, что нужно настоящему джигиту ЛаТеХнику для оформления псевдокодов. Так, нужные параметры приведены в разделе 6, а в разделе 3.2 приведён беспощадный пример, в котором показаны чуть ли не все элементы, которые умеет воспроизводить algorithm2e.

Как вставить код MATLAB в документ LaTeX

Для подсветки синтаксиса и вставки программного кода MATLAB в LaTeX есть специальный пакет расширений под незамысловатым названием mcode. Для использования этого пакета добавляем строчку в преамбулу:

\usepackage[usenames,dvipsnames]{color}
\usepackage[numbered,framed]{mcode}

Обращаю внимание на то, что mcode должно идти после упоминания пакета color. Теперь, у mcode есть несколько параметров, а именно:

• bw - по умолчанию код будет раскрашен так, как он видится в редакторе MATLAB, с зелёными комментариями. Параметр bw сделает весь код в оттенках серого.
• numbered - включает нумерацию строк в коде (удобно, если вы обсуждаете в статье детали алгоритма).
• framed -  рисует вокруг кода рамку.

Дальше всё просто - вставляем  кусок программного кода на MATLAB:

\begin{lstlisting}
% Example Matlab code for calculating hypotenuse
% $c = \sqrt{a^2+b^2}$ §
a = 3;
b = 4;
c = sqrt(a^2+b^2);
\end{lstlisting}

И вот что мы увидим в документе:

На самом деле, всё, что делает mcode, это конфигурирует пакет расширений listings - просто вся черновая работа делается за вас. Вот сейчас начнётся настоящий хардкор, ибо мы переходим к пакету listings...

Оформление исходного кода программ в LaTeX с помощью listings
Самый мощный и кошмарный пакет LaTeX - listings, который может почти всё (кроме заваривания кофе), но самая большая проблема - выяснить, как и что со всем этим делать.  В этом посте я просто приведу пример применения пакета listings и описание его настроек, чтобы самому не пришлось перечитывать кошмарную документацию listings.pdf

Для примера вставим исходный код программы на С в документ LaTeX с помощью listings.

Сразу скажу: всё нижеперечисленное приведено для английского языка, чтобы не огрести проблем ещё и с кириллицей. С языком осин и берёз listings дружит плохо, и кроме того, не переваривается latex2rtf - это важно, когда документ будет конвертироваться в ворд.

Сначала правим преамбулу документа:

\documentclass[a4paper,10pt]{article}

\usepackage{color} %% это для отображения цвета в коде
\usepackage{listings} %% собственно, это и есть пакет listings

\usepackage{caption}
\DeclareCaptionFont{white}{\color{white}} %% это сделает текст заголовка белым
%% код ниже нарисует серую рамочку вокруг заголовка кода.
\DeclareCaptionFormat{listing}{\colorbox{gray}{\parbox{\textwidth}{#1#2#3}}}
\captionsetup[lstlisting]{format=listing,labelfont=white,textfont=white}

\begin{document}

Теперь уже внутри документа настраиваем вид оформление исходника   программы на С. Здесь я привёл основные параметры с пояснениями, что они делают:

\lstset{ %
language=C,                 % выбор языка для подсветки (здесь это С)
basicstyle=\small\sffamily, % размер и начертание шрифта для подсветки кода
numbers=left,               % где поставить нумерацию строк (слева\справа)
numberstyle=\tiny,           % размер шрифта для номеров строк
stepnumber=1,                   % размер шага между двумя номерами строк
numbersep=5pt,                % как далеко отстоят номера строк от подсвечиваемого кода
backgroundcolor=\color{white}, % цвет фона подсветки - используем \usepackage{color}
showspaces=false,            % показывать или нет пробелы специальными отступами
showstringspaces=false,      % показывать или нет пробелы в строках
showtabs=false,             % показывать или нет табуляцию в строках
frame=single,              % рисовать рамку вокруг кода
tabsize=2,                 % размер табуляции по умолчанию равен 2 пробелам
captionpos=t,              % позиция заголовка вверху [t] или внизу [b] 
breaklines=true,           % автоматически переносить строки (да\нет)
breakatwhitespace=false, % переносить строки только если есть пробел
escapeinside={\%*}{*)}   % если нужно добавить комментарии в коде
}

Вставляем приведённые выше заклинания в тело документа и после этого куска кода вставляем, собственно, оформление исходника:

\begin{lstlisting}[label=some-code,caption=Some Code]
int main(void) // main routine
{
int i, j; // Initialisation of counters

// The code below prints the 3x3 matrix
for (i=0; i<3; ++i) {
for (j=0; j<3; ++j) printf("%5.1f", m[i*3+j]);
putchar('\n');
}

cblas_dgemv(CblasRowMajor, CblasNoTrans,
3, 3, 1.0, m, 3, x, 1, 0.0, y, 1);

// The code below prints the 3x3 matrix - result of multiplication
for (i=0; i<3; ++i) printf("%5.1f\n", y[i]);

return 0;
}

\end{lstlisting}

Это всё должно скомпилироваться и выдать следующий результат:

Сравнительно красиво, в цвете и с кучей настроек. Остальные 1350 тумблеров, настроек и параметров вы найдёте в документации listings.pdf

Замечание: Оказывается, algortithm2e очень не любит, когда вставляют разрыв строк - ругается, что пропущен параграф:
[LaTeX] digest-optimizationActiveSet.tex => digest-optimizationActiveSet.dvi (latex)
[LaTeX] finished with exit status 1
digest-optimizationActiveSet.tex:0:File ended while scanning use of \algocf@For.
[LaTeX] 1 error, 0 warnings, 0 badboxes

Listings и Хохруссиш... 

не созданы друг для друга. Можно попробовать рецепт в виде:

\lstset{language=Java,inputencoding=utf8x, extendedchars=\true ...

предложенный здесь (в комментариях), но listings не работает нормально с русским текстом, состоящим более, чем из одного слова

Зато listings работает с олдскульной и ортодоксальной koi8-r. Для это вставляем в преамбулу:

\usepackage[T2A]{fontenc}
\usepackage[koi8-r]{inputenc}%включаем свою кодировку: koi8-r или utf8 в UNIX, cp1251 в Windows
\renewcommand{\lstlistingname}{Листинг}

и далее меняем оформление исходника на это:

\begin{lstlisting}[label=some-code,caption={Это крутой исходный код}]
int main(void) // главная программа
{
int i, j; // инициализация счётчиков

// Сей код множит матрицу величиною 3x3
for (i=0; i<3; ++i) {
for (j=0; j<3; ++j) printf("%5.1f", m[i*3+j]);
putchar('\n');
}

// Вызов басурманской библиотеки BLAS
cblas_dgemv(CblasRowMajor, CblasNoTrans,
3, 3, 1.0, m, 3, x, 1, 0.0, y, 1);

// Подаём челобитную на экран
for (i=0; i<3; ++i) printf("%5.1f\n", y[i]);

return 0;
}
\end{lstlisting}

В итоге мы получим кириллизованный фрагмент кода:

Нашедшие рабочий рецепт с listings и комментариями на русском в utf8 приглашаются им поделиться в комментариях.

Итоги дискуссии по оформлению программного кода с русскими комментариями в listings: решение в использовании команд escapechar=  или конвертацией документа в koi8/cp1251. Больше подробностей по этим ссылкам. Спасибо Роману Химову и Alexanius за ценные замечения в комментариях.

Тем не менее, listings, хотя и не идеален, но представляет собой наиболее гибкое решение.


Альтернативы
Есть и другие способы добиться от LaTeX большой и чистой любви раскраски и подсветки исходного кода.

highlight

Среди альтернатив выделяется во всех смыслах программа highlight, которая может быть использована для генерации LaTeX-разметки из исходника. Хорошая новость - у highlight проблем с UTF8 нет. Плохая новость в том, что highlight преобразует код таким образом, что его сложно корректировать вручную.

source-highlight

Другой вариант - использовать программу source-highlight, которая имеется в частности в репозиториях Debian. Установка не отнимет много сил и времени:

apt-get install source-highligh

и далее в командной строке пишем:

source-highlight --input code.c --out-format latexcolor --src-lang=C  --line-number > code.tex

То есть раскрасить исходный код из файла и выдать в теховский файл code.tex для вставки в документ. Выхлоп source-highlight выглядит вот так:

\noindent
\mbox{}\texttt{\textcolor{Black}{01:}} \ \textcolor{ForestGreen}{int}\ \textbf{\textcolor{Black}{main}}\textcolor{BrickRed}{(}\textcolor{ForestGreen}{void}\textcolor{BrickRed}{)} \\
\mbox{}\texttt{\textcolor{Black}{02:}} \textcolor{Red}{\{} \\
\mbox{}\texttt{\textcolor{Black}{03:}} \ \ \textcolor{ForestGreen}{int}\ i\textcolor{BrickRed}{,}\ j\textcolor{BrickRed}{;} \\
\mbox{}\texttt{\textcolor{Black}{04:}} \\
\mbox{}\texttt{\textcolor{Black}{05:}} \ \ \textbf{\textcolor{Blue}{for}}\ \textcolor{BrickRed}{(}i\textcolor{BrickRed}{=}\textcolor{Purple}{0}\textcolor{BrickRed}{;}\ i\textcolor{BrickRed}{\textless{}}\textcolor{Purple}{3}\textcolor{BrickRed}{;}\ \textcolor{BrickRed}{++}i\textcolor{BrickRed}{)}\ \textcolor{Red}{\{} \\
\mbox{}\texttt{\textcolor{Black}{06:}} \ \ \ \ \textbf{\textcolor{Blue}{for}}\ \textcolor{BrickRed}{(}j\textcolor{BrickRed}{=}\textcolor{Purple}{0}\textcolor{BrickRed}{;}\ j\textcolor{BrickRed}{\textless{}}\textcolor{Purple}{3}\textcolor{BrickRed}{;}\ \textcolor{BrickRed}{++}j\textcolor{BrickRed}{)}\ \textbf{\textcolor{Black}{printf}}\textcolor{BrickRed}{(}\texttt{\textcolor{Red}{"{}\%5.1f"{}}}\textcolor{BrickRed}{,}\ m\textcolor{BrickRed}{[}i\textcolor{BrickRed}{*}\textcolor{Purple}{3}\textcolor{BrickRed}{+}j\textcolor{BrickRed}{]);} \\
\mbox{}\texttt{\textcolor{Black}{07:}} \ \ \ \ \textbf{\textcolor{Black}{putchar}}\textcolor{BrickRed}{(}\texttt{\textcolor{Red}{'}}\texttt{\textcolor{CarnationPink}{\textbackslash{}n}}\texttt{\textcolor{Red}{'}}\textcolor{BrickRed}{);} \\
\mbox{}\texttt{\textcolor{Black}{08:}} \ \ \textcolor{Red}{\}} \\
\mbox{}\texttt{\textcolor{Black}{09:}} \\
\mbox{}\texttt{\textcolor{Black}{10:}} \ \ \textbf{\textcolor{Black}{cblas$\_$dgemv}}\textcolor{BrickRed}{(}CblasRowMajor\textcolor{BrickRed}{,}\ CblasNoTrans\textcolor{BrickRed}{,}\ \textcolor{Purple}{3}\textcolor{BrickRed}{,}\ \textcolor{Purple}{3}\textcolor{BrickRed}{,}\ \textcolor{Purple}{1.0}\textcolor{BrickRed}{,}\ m\textcolor{BrickRed}{,}\ \textcolor{Purple}{3}\textcolor{BrickRed}{,}\ x\textcolor{BrickRed}{,}\ \textcolor{Purple}{1}\textcolor{BrickRed}{,}\ \textcolor{Purple}{0.0}\textcolor{BrickRed}{,}\ y\textcolor{BrickRed}{,}\ \textcolor{Purple}{1}\textcolor{BrickRed}{);} \\
\mbox{}\texttt{\textcolor{Black}{11:}} \\
\mbox{}\texttt{\textcolor{Black}{12:}} \\
\mbox{}\texttt{\textcolor{Black}{13:}} \ \ \textbf{\textcolor{Blue}{for}}\ \textcolor{BrickRed}{(}i\textcolor{BrickRed}{=}\textcolor{Purple}{0}\textcolor{BrickRed}{;}\ i\textcolor{BrickRed}{\textless{}}\textcolor{Purple}{3}\textcolor{BrickRed}{;}\ \textcolor{BrickRed}{++}i\textcolor{BrickRed}{)}\ \ \textbf{\textcolor{Black}{printf}}\textcolor{BrickRed}{(}\texttt{\textcolor{Red}{"{}\%5.1f}}\texttt{\textcolor{CarnationPink}{\textbackslash{}n}}\texttt{\textcolor{Red}{"{}}}\textcolor{BrickRed}{,}\ y\textcolor{BrickRed}{[}i\textcolor{BrickRed}{]);} \\
\mbox{}\texttt{\textcolor{Black}{14:}} \\
\mbox{}\texttt{\textcolor{Black}{15:}} \ \ \textbf{\textcolor{Blue}{return}}\ \textcolor{Purple}{0}\textcolor{BrickRed}{;} \\

\mbox{}\texttt{\textcolor{Black}{16:}} \textcolor{Red}{\}}

В общем, запасайтесь дьяволы гробами. Выглядит результат вот так:

Автор source-highlight явно покуривает что-то очень весёлое и бодрящее, на что легко может возбудиться ФСКН :-) Для работы всей этой светомузыки в преамбуле документа должна быть команда:

\usepackage[usenames,dvipsnames]{color}

В целом, это костыль, конечно, но он, скажем так, работает.


Ссылки...
... приведены в посте выше, хотя это не предел человеческой фантазии, и имеют место быть альтернативы:

• пакет fancyvrb для создания более продвинутого окружения verbatim;
• пакет minted, основанный на Pygments, тоже может раскрашивать код.

Если уважаемые комментаторы накопают другие методы оформления кода в латех - просьба делиться в комментариях.