Tx · LaTeX & TikZ

How to Highlight Multiline MATLAB Comments with Listings

Published By the 9to5Science editorial team

At a glance

  1. 1. Keep line comments

    Use MATLAB’s normal percent-sign line comments; add the block-comment rule rather than replacing the existing comment rule.

  2. 2. Set block delimiters

    Configure listings to start a block comment at %{ and end it at %}.

  3. 3. Compile an example

    Use a MATLAB listing containing the delimiters on their own lines, as MATLAB requires.

MATLAB uses % for ordinary line comments and %{ … %} for a block comment. The listings package does not always recognize the block form automatically, so add a comment delimiter pair to the MATLAB language settings.

The braces in the delimiter strings need escaping because braces also group LaTeX option values. The example below adds the block-comment pair while leaving MATLAB’s usual % line comments available.

Minimal working example

Save this as a .tex file and compile it with pdfLaTeX or another standard LaTeX engine:

\documentclass{article}
\usepackage{xcolor}
\usepackage{listings}

\lstdefinestyle{matlab}{
  language=Matlab,
  morecomment=[s]{\%\{} {\%\}},
  commentstyle=\color{green!40!black}\itshape
}

\begin{document}

\begin{lstlisting}[style=matlab]
x = 1; % ordinary line comment

%{
This is a block comment.
It can span several lines.
%}
y = x + 1;
\end{lstlisting}

\end{document}

Whitespace between the two delimiter arguments is optional. The compact form of the option is:

morecomment=[s]{\%\{}{\%\}}

That line tells listings to begin a comment at %{ and stop at %}. The \% represents a literal percent sign, while \{ and \} represent literal braces rather than LaTeX option-grouping braces. morecomment adds a delimiter rule; using comment instead can replace existing comment definitions and may cause ordinary % comments to stop being highlighted as expected.

The example loads xcolor for the chosen comment color. If you do not want colored comments, remove \usepackage{xcolor} and set commentstyle=\itshape instead.

Why the delimiters must be on separate lines

This configuration recognizes the opening and closing character sequences. It does not validate MATLAB syntax. In MATLAB source, %{ and %} must each appear alone on a line, apart from whitespace. Write a block comment like this:

%{
Notes about the following calculation.
These lines are comments, not executable code.
%}

Do not put code after %{ or %} on the same line and expect MATLAB to treat it as a valid block-comment boundary. The listings highlighter may still color text according to the delimiter sequence even when the source does not follow MATLAB’s syntax rules.

Apply the rule to every MATLAB listing

The example defines a reusable style named matlab. Apply it to a listing with style=matlab, or set it as the document-wide default:

\lstset{style=matlab}

After that, MATLAB listings can be written without repeating the style option:

\begin{lstlisting}
%{
A longer explanation belongs here.
%}
result = calculate_value();
\end{lstlisting}

If your document already has a MATLAB style, add the morecomment line to that style rather than defining a second one. Keep any existing language, keyword, number, and frame settings.

Common mistakes

  • Leaving out the escaped braces. Writing a delimiter as {%{} confuses LaTeX’s grouping with the literal brace in MATLAB’s %{ token. Use \%\{ for the opening token and \%\} for the closing token.
  • Using the same delimiter at both ends. MATLAB’s block form begins with %{ and ends with %}; a pair of percent signs does not describe it.
  • Replacing the line-comment rule. Add the block form with morecomment=[s]. Avoid redefining the language’s comments unless you also specify the ordinary % line-comment behavior.
  • Expecting syntax checking. listings formats text; it does not parse MATLAB or report whether block delimiters are placed legally.

If block comments are not highlighted, first check that the exact morecomment=[s]{\%\{}{\%\}} option is inside the style or \lstset braces and that the source uses %{ and %} exactly.

References

  1. The Listings Package: Typeset Source Code Listings (CTAN)

Spotted an error? Send a correction. Read how we write and check articles in our editorial policy.