Debian Codegraph @

texmf-dist/source/latex/matlab-prettifier/matlab-prettifier.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2014 by Julien Cretel
4 % <jubobs.matlab.prettifier at gmail.com>
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<package>\NeedsTeXFormat{LaTeX2e}[2011/06/27]
20 %<package>\ProvidesPackage{matlab-prettifier}
21 %<package> [2014/06/19 v0.3 A package for prettyprinting Matlab source code]
22 %
23 %<*driver>
24 \documentclass[a4paper]{ltxdoc}
25 \EnableCrossrefs
26 \CodelineIndex
27 \RecordChanges
28
29 \usepackage[T1]{fontenc}
30 \usepackage{lmodern}
31 \usepackage{xcolor}
32 \usepackage{lstdoc}
33 \usepackage[framed,numbered]{matlab-prettifier}
34 \usepackage{hyperref}
35 \usepackage{cleveref}
36
37 \lstset
38 {
39 style = Matlab-editor,
40 basicstyle = \normalsize\mlttfamily,
41 upquote = true,
42 mlunquotedstringdelim = {/*}{*/},
43 mlmoresharedvars = {myglobalvar},
44 }
45 \lstdefinestyle{nonbnoframe}
46 {
47 frame = none,
48 numbers = none,
49 }
50 \lstMakeShortInline"
51 \newcommand\ph\mlplaceholder
52 \newcommand*{\pkg}[1]{\textsf{#1}}
53 \newcommand*{\opt}[1]{\texttt{#1}}
54 \newcommand\lstpkg{\pkg{listings}}
55 \newcommand*{\lststy}[1]{\texttt{#1}}
56 \newcommand*{\lstlng}[1]{\texttt{#1}}
57 \newcommand\matlab{\textsc{Matlab}}
58 \newcommand\octave{\textsc{Octave}}
59 \newcommand\matlabver{\matlab~(R2013a)}
60 \newcommand\mathworks{MathWorks}
61 \newcommand*\trademark[1]{#1\textsuperscript{\textregistered}}
62 \newcommand\mlpkg{\pkg{matlab-prettifier}}
63 \newcommand\mllng{\texttt{Matlab-pretty}}
64 \newcommand*{\mlsty}[1]{\texttt{#1}}
65 \newcommand\overrideEnd{\lstinline[mloverride]|end|}
66 \newcommand\overrideEnumeration{\lstinline[mloverride]|enumeration|}
67 \newcommand\overrideMethods{\lstinline[mloverride]|methods|}
68 \newcommand\overrideProperties{\lstinline[mloverride]|properties|}
69 \newcommand\overrideEvents{\lstinline[mloverride]|events|}
70 \newcommand\itemp{\item[\(+\)]}
71 \newcommand\itemm{\item[\(-\)]}
72
73 \makeindex
74
75 \begin{document}
76 \DocInput{matlab-prettifier.dtx}
77 \end{document}
78 %</driver>
79 % \fi
80 %
81 % \CheckSum{671}
82 %
83 % \CharacterTable
84 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
85 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
86 % Digits \0\1\2\3\4\5\6\7\8\9
87 % Exclamation \! Double quote \" Hash (number) \#
88 % Dollar \$ Percent \% Ampersand \&
89 % Acute accent \' Left paren \( Right paren \)
90 % Asterisk \* Plus \+ Comma \,
91 % Minus \- Point \. Solidus \/
92 % Colon \: Semicolon \; Less than \<
93 % Equals \= Greater than \> Question mark \?
94 % Commercial at \@ Left bracket \[ Backslash \\
95 % Right bracket \] Circumflex \^ Underscore \_
96 % Grave accent \` Left brace \{ Vertical bar \|
97 % Right brace \} Tilde \~}
98 %
99 % \changes{v0.1}{2014/04/24}{Initial release.}
100 % \changes{v0.2}{2014/04/25}{
101 % Refactor code extensively;
102 % rewrite automatic scaling of inline code;
103 % implement mlscaleinline key;
104 % implement mlonlyheader.
105 % }
106 % \changes{v0.3}{2014/06/19}{
107 % Change default font from Bera Mono to Computer Modern typewriter
108 % (for compatibility reasons);
109 % fix bug (end keyword now gets reset by a semicolon);
110 % rename placeholder user macro;
111 % mention support for a subset of Octave's syntax.
112 % }
113 %
114 % \GetFileInfo{matlab-prettifier.sty}
115 %
116 % ^^A see http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex%2F3540
117 % \begingroup
118 % \def\x{\#,\$,\%,\^,\_,\~,\&,\{,\},\/}%^^A
119 % \makeatletter
120 % \@onelevel@sanitize\x
121 % \expandafter\endgroup\expandafter\DoNotIndex\expandafter{\x}
122 %
123 % \begingroup
124 % \makeatletter
125 % \lccode`9=32\relax
126 % \lowercase{%^^A
127 % \edef\x{\noexpand\DoNotIndex{\@backslashchar9}}%^^A
128 % }%^^A
129 % \expandafter\endgroup\x
130 %
131 % \DoNotIndex{\@empty,\@ifpackagewith,\@lst,\@namedef,\@ne,\@tempa}
132 % \DoNotIndex{\advance}
133 % \DoNotIndex{\baselineskip,\begingroup,\bfseries,\bgroup}
134 % \DoNotIndex{\ClosingEndKW@mlpr@false,\ClosingEndKW@mlpr@true,^^A
135 % \color,\colorlet,\csname,\CurrentOption}
136 % \DoNotIndex{\DeclareOption,\def,\definecolor,\dimexpr,^^A
137 % \DroppingOutput@mlpr@false,\DroppingOutput@mlpr@true}
138 % \DoNotIndex{\edef,\egroup,\else,\endcsname,\endgroup,\expandafter}
139 % \DoNotIndex{\f@baselineskip,\f@shape,\f@size,\fi,\font,\fontsize,^^A
140 % \fontchardp,\fontcharht,\fontfamily,\framed@mlpr@true,\fvm@Scale}
141 % \DoNotIndex{\gdef,\global}
142 % \DoNotIndex{\ifnum,\ifx,^^A
143 % \InClassdef@mlpr@false,\InClassdef@mlpr@true,^^A
144 % \InSecTitle@mlpr@false,\InSecTitle@mlpr@true,^^A
145 % \InStr@mlpr@false,\InStr@mlpr@true,^^A
146 % \itdefault,\itshape}
147 % \DoNotIndex{\let,\lst@basicstyle,\lst@BeginDropOutput,\lst@AddToHook,^^A
148 % \lst@CalcLostSpaceAndOutput,\lst@DefSaveDef,\lst@DelimKey,^^A
149 % \lst@EnterMode,\lst@ifdisplaystyle,\lst@ifLmode,\lst@ifwhitespace,^^A
150 % \lst@InstallKeywords,\lst@Key,\lst@language,\lst@LeaveMode,^^A
151 % \lst@lineno,\lst@linewidth,\lst@Lmodetrue,\lst@mode,\lst@modetrue,^^A
152 % \lst@NormedDef,\lst@Pmode,\lst@DeleteKeywords,\lst@InstallFamily@,^^A
153 % \lst@MakeKeywords,\lst@MakeMoreKeywords,\lst@UseFamily,^^A
154 % \lstdefinelanguage,\lstdefinestyle,\lstKV@SetIf}
155 % \DoNotIndex{\m@ne,\makebox}
156 % \DoNotIndex{\newcommand,\newcount,\newif,\newlength,\newtoks,\normalsize,^^A
157 % \numbered@mlpr@true,\noexpand}
158 % \DoNotIndex{\OptionNotUsed}
159 % \DoNotIndex{\PackageError,\PackageWarning,\ProcessOptions}
160 % \DoNotIndex{\raisebox,\relax,\renewcommand,\RequirePackage,\rule,\rmfamily}
161 % \DoNotIndex{\selectfont,\setlength,\sldefault,\textlangle,\textrangle,^^A
162 % \ttfamily}
163 % \DoNotIndex{\the}
164 % \DoNotIndex{\upshape}
165 % \DoNotIndex{\VisCharOccured@mlpr@true,\VisCharOccured@mlpr@false}
166 %
167 % \title^^A
168 % {^^A
169 % The \mlpkg{} package^^A
170 % \thanks^^A
171 % {^^A
172 % This document corresponds to \mlpkg~\fileversion,
173 % dated~\filedate.^^A
174 % }^^A
175 % }
176 % \author{Julien Cretel\\ \texttt{jubobs.matlab.prettifier at gmail.com}}
177 % \date{\filedate}
178 % \thispagestyle{empty}
179 % \maketitle
180 %
181 % \begin{abstract}
182 % Built on top of the \lstpkg{} package, the \mlpkg{} package allows you to
183 % effortlessly prettyprint \matlab{} source code in documents typeset with
184 % \LaTeX{} \& friends. Three predefined styles, one of which closely mimics
185 % that of the \matlab{} editor, are available and can be invoked by
186 % \lstpkg{} macros and environments in conjunction with (most) options
187 % provided by the \lstpkg{} package. The appearance of your \matlab{}
188 % listings can be further tweaked via a key-value interface extending that
189 % of \lstpkg{}'. Partial support for Octave syntax is provided.
190 % \end{abstract}
191 %
192 % \tableofcontents\newpage
193 %
194 %
195 % \part{Introduction}
196 %
197 % \section{Why this package?}
198 %
199 % \trademark{\matlab} is a high-level language and interactive environment for
200 % numerical computation, visualization, and programming.^^A
201 % \footnote{Source: \url{http://www.mathworks.co.uk/products/matlab/}}
202 % Despite being proprietary and occasionally frustrating, \matlab{} remains a
203 % great tool for prototyping matrix-oriented, number-crunching programs.
204 % As such, it enjoys widespread popularity, especially in academia,
205 % where, in particular, it is often used for teaching numerical methods.
206 %
207 % Users of both \matlab{} and \LaTeX{} (and friends) often need to typeset
208 % \matlab{} listings in \LaTeX{} documents, usually with some syntax
209 % highlighting, for improved code readability;
210 % the relatively large number of relevant questions posted on
211 % \href{http://tex.stackexchange.com/search?q=matlab+code+is%3Aquestion}^^A
212 % {tex.stackexchange.com} attests to that need.
213 %
214 % Recent versions of \matlab{} provide a built-in function, called "publish",
215 % that can generate \LaTeX{} code for typesetting \matlab{} listings, but
216 % that function uses a |verbatim| environment, which doesn't allow for any
217 % fancy formatting.
218 % Several \LaTeX{} packages^^A
219 % ---vanilla \lstpkg{}, \pkg{mcode}, and \pkg{minted}, among others---^^A
220 % allow for automatic syntax highlighting of \matlab{} listings in \LaTeX{}
221 % documents.
222 % However, none of those packages do a great job at replicating the very
223 % specific syntax-highlighting style performed on the fly by the \matlab{}
224 % editor.^^A
225 % \footnote{see ... for a comparison.}
226 %
227 % The lack of tools for faithfully mimicking the style of the \matlab{}
228 % editor is unfortunate, especially from an educational standpoint, for the
229 % following reason.
230 % Most newcomers to \matlab{} read and write code in the \matlab{} editor
231 % and are, therefore, continually exposed to its highlighting style.
232 % Visual cues^^A
233 % ---such as those provided by syntax highlighting---^^A
234 % play an important role for recognising patterns,
235 % and students of a programming language are more likely to quickly and
236 % effectively learn and recognize its syntax if they see it highlighted in a
237 % consistent manner, whether it be in a text editor or in some course material
238 % (lab handout, assignment paper, etc.).
239 %
240 % The \mlpkg{} package is intended to fill that gap.
241 % Built on top of the feature-rich \lstpkg{} package, \mlpkg{} allows you to
242 % beautifully and effortlessly typeset \matlab{} listings, as it configures
243 % \lstpkg{} ``behind the scenes'' to replicate, as closely as possible, the
244 % syntax-highlighting style of the \matlab{} editor.
245 %
246 % What about code written in \octave{} (a free alternative to \matlab{})?
247 % Because \octave{}'s syntax and \matlab{}'s syntax
248 % \href{http://wiki.octave.org/FAQ#How_is_Octave_different_from_Matlab.3F}
249 % {overlap a lot},
250 % \mlpkg{} correctly highlights \octave{} listings that strictly adhere to
251 % the subset of syntax that lies in this overlap.
252 % More support for \octave{} is expected to ship with a future release.
253 %
254 % Furthermore, \mlpkg{} comes with a few additional features that should make
255 % your life easier. Read on!
256 %
257 %
258 % \section{Review of alternatives to \mlpkg{}}
259 %
260 % Here is a review of the different alternatives^^A
261 % ---other than the \mlpkg{} package and \matlab{}'s "publish" function---^^A
262 % available for typesetting \matlab{} listings in \LaTeX{} documents.
263 %
264 % \paragraph{\lstpkg{}' \lstlng{Matlab} language}
265 %^^A
266 % \begin{itemize}
267 % \itemp A starting point!
268 % \itemp \lstpkg{}' rich features are available.
269 % \itemp Settings for \matlab{} listings are bundled into a \lstpkg{}
270 % language, which can be invoked \emph{locally}.
271 % \itemm Some \matlab{} keywords (e.g.\ "parfor") are not listed.
272 % \itemm Built-in \matlab{} function names (e.g.\ "sum") get highlighted
273 % like \matlab{} keywords do, which is very distracting.
274 % \itemm Highlighting of keywords is not context-aware;
275 % in particular, the |end| keyword gets typeset in the same style,
276 % regardless of the context (closing keyword or last-element keyword)
277 % in which it occurs.
278 % \itemm No highlighting of block comments
279 % \itemm No highlighting of line-continuation token and associated comment
280 % \itemm Section titles are not highlighted in a style distinct from that of
281 % comments.
282 % \itemm No highlighting of unquoted strings
283 % \end{itemize}
284 %
285 % \paragraph{\pkg{mcode}}
286 %^^A
287 % \begin{itemize}
288 % \itemp An honest attempt at improving \lstpkg{}' \lstlng{Matlab} language
289 % \itemp Package options for quickly effecting global changes to the look
290 % of \matlab{} listings
291 % \itemp Block comments are highlighted as such.
292 % \itemp A line-continuation token activates comment style\ldots
293 % \itemm \ldots but also gets highlighted in comment style.
294 % \itemm Settings for \matlab{} listings are defined \emph{globally}
295 % (using |\lstset|) rather than locally,
296 % which means those settings can easily be overwritten/lost.
297 % \itemm The \overrideEnumeration{} keyword is not listed.
298 % \itemm Highlighting of the last-element keyword is handled by a series of
299 % literate replacements;
300 % this approach works well only in a limited number of cases in which
301 % that keyword occurs.
302 % \itemm Highlighting of the four context-sensitive class-definition
303 % keywords is not context-aware;
304 % in particular, |properties| gets typeset in the same style,
305 % regardless of the context (function or class-definition keyword)
306 % in which it occurs.
307 % \itemm Undesirable literate replacements
308 % ("<=" by~\(\leq\), "delta" by~\(\Delta\)) are forced upon the users,
309 % and cannot be easily prevented without breaking other literate
310 % replacements put in place for highlighting the last-element keyword.
311 % \itemm Section titles are not highlighted in a style distinct from that of
312 % comments.
313 % \itemm No highlighting of unquoted strings
314 % \itemm The implementation of \pkg{mcode} lacks ``namespacing'',
315 % which increases the risk of conflict with other packages.
316 % \itemm \pkg{mcode} is currently not available on
317 % \href{http://ftp.heanet.ie/pub/CTAN/tex/support/ctanify/ctanify.pdf}
318 % {CTAN}.
319 % \end{itemize}
320 %
321 % \paragraph{Pygments-based packages
322 % (\pkg{minted}, \pkg{verbments}, \pkg{pythontex})}
323 %^^A
324 % \begin{itemize}
325 % \itemp Python!
326 % \itemp Pygments!
327 % \itemp Slick look
328 % \itemp Block comments are highlighted as such.
329 % \itemp A line-continuation token activates comment style\ldots
330 % \itemm \ldots but also gets highlighted in comment style.
331 % \itemm \lstpkg{}' features are not available.
332 % \itemm Highlighting of keywords is not context-aware;
333 % in particular, the last-element keyword gets highlighted like the
334 % closing keyword does, which is very distracting.
335 % \itemm \matlab{}'s transpose operator (".'") and "}'" are incorrectly
336 % interpreted as starting a string literal.
337 % \itemm No highlighting of unquoted strings
338 % \itemm Escape to \LaTeX{} is only allowed in comments.
339 % \itemm Slow compared to \lstpkg{}
340 % \itemm Requires |-shell-escape|
341 % \end{itemize}
342 %
343 %
344 % \section{Syntactic elements automatically highlighted by \mlpkg{}}
345 %
346 % The \mlpkg{} package defines a \pkg{listings} language called
347 % \mllng{}, which is designed to keep track of the context behind the scenes
348 % and, therefore, facilitates context-sensitive highlighting of various
349 % elements of \matlab{} syntax.
350 % That language is used as a basis for three \lstpkg{} styles,
351 % one of which, called \mlsty{Matlab-editor}, is showcased below.
352 %
353 % \paragraph{Context-insensitive keywords}
354 % "while", "for", "break", etc.
355 %
356 % \paragraph{Context-sensitive keywords}
357 % "end",
358 % \overrideEvents{},
359 % \overrideProperties{},
360 % etc.
361 %
362 % \paragraph{Quoted strings}
363 % \mbox{}
364 % \iffalse
365 %<*example>
366 % \fi
367 \begin{lstlisting}[numbers=none]
368 'The sleeper must awaken.'
369 \end{lstlisting}
370 % \iffalse
371 %</example>
372 % \fi
373 %
374 % \paragraph{To-end-of-line and block comments}
375 % \mbox{}
376 % \iffalse
377 %<*example>
378 % \fi
379 \begin{lstlisting}[numbers=none]
380 % Now let's assign the value of pi to variable a
381 a = pi
382 %{
383 Now that a holds the value of pi,
384 here is what we're going to do...
385 blah blah blah
386 %}
387 \end{lstlisting}
388 % \iffalse
389 %</example>
390 % \fi
391 %
392 % \paragraph{Line-continuation token (and associated to-end-of-line comment)}
393 % \mbox{}
394 % \iffalse
395 %<*example>
396 % \fi
397 \begin{lstlisting}[numbers=none]
398 A = [ 1, 2, 3,... (second row defined on next line)
399 4, 5, 6];
400 \end{lstlisting}
401 % \iffalse
402 %</example>
403 % \fi
404 %
405 % \paragraph{Section titles}
406 % \mbox{}
407 % \iffalse
408 %<*example>
409 % \fi
410 \begin{lstlisting}[numbers=none]
411 %% Variable initialization
412 \end{lstlisting}
413 % \iffalse
414 %</example>
415 % \fi
416 %
417 % \paragraph{System commands}
418 % \mbox{}
419 % \iffalse
420 %<*example>
421 % \fi
422 \begin{lstlisting}[numbers=none]
423 ! gzip sample.m
424 \end{lstlisting}
425 % \iffalse
426 %</example>
427 % \fi
428 %
429 %
430 % \section{Styles provided by \mlpkg{}}
431 %
432 % The package defines three \lstpkg{} \emph{styles} for \matlab{} code:
433 % \mlsty{Matlab-editor}, \mlsty{Matlab-bw}, and
434 % \mlsty{Matlab-Pyglike}.
435 % Those styles differ in terms of color scheme but, for convenience,
436 % all three activate automatic line breaking;
437 % for more defails about automatic line breaking, see subsection~4.10 in
438 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
439 %
440 % Here is a comparison of the three styles defined by \mlpkg{}.
441 %
442 % \paragraph{\mlsty{Matlab-editor}}
443 % This style mimics the default style of the \matlab{} editor.
444 % \iffalse
445 %<*example>
446 % \fi
447 \begin{lstlisting}[style=Matlab-editor,basicstyle=\mlttfamily]
448 %% Sample Matlab code
449 !mv test.txt test2.txt
450 A = [1, 2, 3;... foo
451 4, 5, 6];
452 s = 'abcd';
453 for k = 1:4
454 disp(s(k)) % bar
455 end
456 %{
457 create row vector x, then reverse it
458 %}
459 x = linspace(0,1,101);
460 y = x(end:-1:1);
461 \end{lstlisting}
462 % \iffalse
463 %</example>
464 % \fi
465 %
466 % \paragraph{\mlsty{Matlab-bw}}
467 % This style is mainly for black \& white printing.
468 % \iffalse
469 %<*example>
470 % \fi
471 \begin{lstlisting}[style=Matlab-bw,basicstyle=\mlttfamily]
472 %% Sample Matlab code
473 !mv test.txt test2.txt
474 A = [1, 2, 3;... foo
475 4, 5, 6];
476 s = 'abcd';
477 for k = 1:4
478 disp(s(k)) % bar
479 end
480 %{
481 create row vector x, then reverse it
482 %}
483 x = linspace(0,1,101);
484 y = x(end:-1:1);
485 \end{lstlisting}
486 % \iffalse
487 %</example>
488 % \fi
489 %
490 % \paragraph{\mlsty{Matlab-Pyglike}}
491 % The \pkg{minted}, \pkg{verbments}, and \pkg{pythontex} packages all use
492 % \href{http://pygments.org}{Pygments} lexers for syntax highlighting of
493 % listings.
494 % This \mlpkg{} style closely mimics the default style associated with
495 % Pygments' `MatlabLexer'.
496 % \iffalse
497 %<*example>
498 % \fi
499 \begin{lstlisting}[style=Matlab-Pyglike,basicstyle=\mlttfamily]
500 %% Sample Matlab code
501 !mv test.txt test2.txt
502 A = [1, 2, 3;... foo
503 4, 5, 6];
504 s = 'abcd';
505 for k = 1:4
506 disp(s(k)) % bar
507 end
508 %{
509 create row vector x, then reverse it
510 %}
511 x = linspace(0,1,101);
512 y = x(end:-1:1);
513 \end{lstlisting}
514 % \iffalse
515 %</example>
516 % \fi
517 %
518 %
519 % \section{Other features}
520 %
521 % Additional features include
522 %
523 % \begin{itemize}
524 % \item a key-value interface extending that of the \lstpkg{} package,
525 % \item manual highlighting of variables with shared scope
526 % (e.g.\ "myglobalvar"),
527 % \item manual highlighting of unquoted strings
528 % (e.g.\ ``on'' in ``"hold /*on*/"''),
529 % \item a macro for easily typesetting placeholders
530 % (e.g.\ \ph{initial-value}),
531 % \item automatic scaling of inline code according to its surroundings,
532 % \item an option to only print the header of a \matlab{} function.
533 % \end{itemize}
534 %
535 %
536 % \part{User's guide}
537 %
538 % \section{Installation}
539 %
540 % \subsection{Package dependencies}
541 %
542 % \mlpkg{} requires relatively up-to-date versions of packages \pkg{textcomp},
543 % \pkg{xcolor}, and \lstpkg{}, all three of which ship with popular \TeX{}
544 % distributions. It loads those three packages without any options.
545 %
546 %
547 % \subsection{Installing \mlpkg{}}
548 %
549 % Since the package has been officially released on
550 % \href{http://www.ctan.org/pkg/matlab-prettifier}{CTAN},
551 % you should be able to install it directly through your package manager.
552 %
553 % However, if you need to install \mlpkg{} manually, you should run
554 %^^A
555 % \begin{verbatim}
556 % latex matlab-prettifier.ins\end{verbatim}
557 %^^A
558 % and copy the file called |matlab-prettifier.sty| to a path
559 % where \LaTeX{} (or your preferred typesetting engine) can find it.
560 % To generate the documentation, run
561 %^^A
562 % \begin{verbatim}
563 % pdflatex matlab-prettifier.dtx
564 % makeindex -s gglo.ist -o matlab-prettifier.gls matlab-prettifier.glo
565 % makeindex -s gind.ist -o matlab-prettifier.ind matlab-prettifier.idx
566 % pdflatex matlab-prettifier.dtx
567 % pdflatex matlab-prettifier.dtx\end{verbatim}
568 %^^A
569 %
570 %
571 % \section{Getting started}
572 %
573 % As stated above, the \mlpkg{} package is built on top of the \lstpkg{}
574 % package.
575 % If you already are a seasoned \lstpkg{} user, you should feel right at home.
576 % If you're not, be aware that this user's guide makes use of some \lstpkg{}
577 % functionalities (such as key-value options) without describing their usage.
578 % For more details on those functionalities, you should consult the
579 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
580 %
581 %
582 % \subsection{Loading \texorpdfstring{\mlpkg{}}{matlab-prettifier}}
583 %
584 % Simply write
585 %^^A
586 % \begin{verbatim}
587 % \usepackage{matlab-prettifier}\end{verbatim}
588 %^^A
589 % somewhere in your preamble.
590 %
591 % You may want to load the \lstpkg{} and
592 % \pkg{xcolor} packages with some options; in that case, make sure those
593 % options are passed to those two packages \emph{before} loading the \mlpkg{}
594 % package.
595 %
596 % The \mlpkg{} package currently offers four options.
597 % The first two are inspired from the \pkg{mcode} package.
598 % The last two are simply \lstpkg{} options that \mlpkg{} passes to \lstpkg{}
599 % behind the scenes;
600 % I chose to define those two options as \mlpkg{} options to save you
601 % the hassle of loading them with \lstpkg{} separately,
602 % should you wish to use them.
603 %^^A
604 % \begin{description}
605 % \item[\opt{framed}]\leavevmode
606 %
607 % Draws (by default) a dark gray frame around each listing that uses
608 % one of the three styles defined by \mlpkg{}.
609 %
610 % \item[\opt{numbered}]\leavevmode
611 %
612 % Prints (by default) line numbers in light gray to the left of each
613 % listing that uses one of the three styles defined by \mlpkg{}.
614 %
615 % \item[\opt{draft}]\leavevmode
616 %
617 % This is simply \lstpkg{}' \opt{draft} option.
618 % For more details, see subsection~2.2 of the
619 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
620 %
621 % \item[\opt{final}]\leavevmode
622 %
623 % This is simply \lstpkg{}' \opt{final} option.
624 % For more details, see subsection~2.2 of the
625 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
626 % \end{description}
627 %
628 %
629 % \subsection{Displayed listings}
630 %
631 % To typeset a \matlab{} listing embedded in your |tex| file, simply enclose
632 % it in an |lstlisting| environment, and load some style in the environment's
633 % optional argument, using \lstpkg{}' \keyname{style} key.
634 %^^A
635 % \begin{verbatim}
636 % \begin{lstlisting}[style=Matlab-editor]
637 % ...
638 % \end{lstlisting}\end{verbatim}
639 %
640 %
641 % \subsection{Standalone listings}
642 %
643 % In practice, though, keeping your \matlab{} listings in external files^^A
644 % ---rather than embedding them in a |tex|~file---^^A
645 % is preferable, for maintainability reasons.
646 % To typeset a \matlab{} listing residing in an m-file, simply invoke the
647 % |\lstinputlisting| macro; load some style in the environment's
648 % optional argument, and specify the path to the m-file in question in the
649 % mandatory argument.
650 %^^A
651 % \begin{verbatim}
652 % \lstinputlisting[style=Matlab-editor]{sample.m}\end{verbatim}
653 %^^A
654 %
655 %
656 % \subsection{Inline listings}
657 %
658 % You may want to typeset fragments of \matlab{} code within the main text of
659 % your document. For instance, you may want to typeset the "break" keyword in
660 % a sentence, in order to explain its usage.
661 % The |\lstinline| macro can be used for typesetting such inline code.
662 %^^A
663 % \begin{verbatim}
664 % \lstinline[style=Matlab-style]!break!\end{verbatim}
665 %^^A
666 % Well, that's quite a mouthful for such a simple \matlab{} keyword!
667 % Writing |\lstinline| for each instance of inline \matlab{} code in your
668 % document can rapidly become tedious.
669 % Fortunately, \lstpkg{} allows its users to define a character as a shorthand
670 % for inline code via the |\lstMakeShortInline| macro.
671 % For instance, you could define the double-quote character~(|"|) as a
672 % shorthand for inline \matlab{} code with
673 %^^A
674 % \begin{verbatim}
675 % \lstMakeShortInline[style=Matlab-editor]"\end{verbatim}
676 %^^A
677 % and you would then be able to typeset this "break" keyword simply by writing
678 %^^A
679 % \begin{verbatim}
680 % "break"\end{verbatim}
681 %^^A
682 % in your |tex| file (but outside displayed listings, of course).
683 %
684 % You should choose a character that does not otherwise occur in your
685 % |tex| file, especially in the inline \matlab{} code itself,
686 % or you run the risk of confusing \TeX{}.
687 % I find that, in general, the double-quote character~(|"|) offers a good
688 % compromise.
689 % If necessary, you can undefine a character as a shorthand for inline code,
690 % via \lstpkg{}' |\lstDeleteShortInline| macro.
691 % For more details, see subsection~4.17 in the \lstpkg{} manual.
692 %
693 %
694 % \subsection{Placeholders}
695 %
696 % Code-snippet placeholders, such as \ph{initial-value}, are particularly
697 % useful for educational purposes, e.g.\ to describe the syntax of a
698 % programming language to students.
699 % The following macro allows you to typeset such placeholders, both
700 % inside and outside listings:
701 %^^A
702 % \begin{syntax}
703 %
704 % \item[0.1] \rcmdname\mlplaceholder|{|\meta{placeholder content}|}|
705 %
706 % typesets a code-snippet placeholder.
707 % You can use this macro both inside and outside listings.
708 % When used inside listings, it must be invoked within an
709 % \emph{escape to \LaTeX{}}; see subsection~4.14 of the \lstpkg{} manual.
710 %
711 % \end{syntax}
712 %
713 % If you choose to define a single character for escaping to \LaTeX{} (via
714 % \lstpkg{}' \keyname{escapechar} key), I recommend you define
715 % either the double-quote character~(|"|)
716 % or the backtick character~(\texttt{\`{}})
717 % as escape character,
718 % because neither is allowed in \matlab{} statements and expressions^^A
719 % ---although they may occur in \matlab{} string literals.
720 % Note that using~|"| both as shorthand for inline code and as an
721 % escape-to-\LaTeX{} character inside listings is perfectly allowed.
722 %
723 % The following example illustrates how placeholders may be used to describe
724 % the syntax of the \matlab{} while loop.
725 %^^A
726 % \begin{lstsample}{}{\lstset{style=nonbnoframe}}
727 % \begin{lstlisting}[
728 % style=Matlab-editor,
729 % basicstyle=\mlttfamily,
730 % escapechar=`,
731 % ]
732 % while `\mlplaceholder{condition}`
733 % if `\mlplaceholder{something-bad-happens}`
734 % break
735 % else
736 % % do something useful
737 % end
738 % end
739 % \end{lstlisting}
740 % \end{lstsample}
741 %
742 % For convenience, you can of course define a custom macro with a shorter
743 % name for typesetting placeholders, e.g.~|\ph|:
744 %^^A
745 % \begin{verbatim}
746 % \newcommand\ph\mlplaceholder\end{verbatim}
747 %
748 %
749 % \section{Advanced customization}
750 %
751 % The \lstpkg{} package provides a large number of options accessible via a
752 % nifty key-value interface, which is described in its excellent
753 % \href{http://www.ctan.org/pkg/listings}{documentation}.
754 % The \mlpkg{} package extends \lstpkg{}' key-value interface interface by
755 % defining several additional keys that allow you to customize the style of
756 % your \matlab{} listings, should you wish to do so.
757 % All the keys provided by \mlpkg{} are prefixed by ``|ml|'',
758 % to help you distinguish them from native \lstpkg{} keys.
759 %
760 %
761 % \subsection{Keys from the \lstpkg{} that you should not use}
762 %
763 % The great majority of keys provided by \lstpkg{} can be used in conjunction
764 % with keys provided by \mlpkg{} without any detrimental side effects,
765 % but there are a few exceptions that you should keep in mind.
766 %
767 % Some \mlpkg{} keys rely on \lstpkg{} keys ``under the hood'',
768 % and using those \mlpkg{} and \lstpkg{} keys in conjunction is
769 % \emph{strongly discouraged},
770 % because doing so has the potential to wreak havok on the syntax highlighting
771 % of \matlab{} listings.
772 % It would be like \emph{crossing the streams}: it would be \emph{bad}!
773 %
774 % For instance, if you want to change the way \matlab{} keywords are typeset,
775 % you should use the dedicated \mlpkg{} key called \rkeyname{mlkeywordstyle}
776 % and eschew the \lstpkg{} key called \keyname{keywordstyle}.
777 % More generally, if \lstpkg{} provides a key called \meta{something} and
778 % \mlpkg{} provides a key called |ml|\meta{something},
779 % customization of your \matlab{} listings should be done with the latter, not
780 % the former.
781 %
782 %
783 % \subsection{Changing the font of Matlab listings}
784 %
785 % For compatibility reasons, the \mlpkg{} package uses the Computer Modern
786 % typewriter font by default.
787 % However, this font is far from ideal,
788 % because it doesn't come with a boldface version,
789 % and the \matlab{} editor does display some elements of \matlab{} syntax
790 % (section titles) in boldface.
791 % Therefore, I encourage you to switch to your preferred ``programmer font''
792 % instead; how to do that depends on which typesetting engine you use.
793 %
794 % For |pdflatex| users,
795 % \mlpkg{} conveniently provides a macro for easily selecting the Bera Mono
796 % font---which is a popular monospaced font for listings,
797 % and the one I used for all listings in this manual.
798 %^^A
799 % \begin{syntax}
800 %
801 % \item[0.1] \rcmdname\mlttfamily
802 %
803 % selects the Bera Mono font (somewhat scaled down).
804 %
805 % \end{syntax}
806 %^^A
807 % To use Bera Mono in your \matlab{} listings, you must pass |\mltttfamily| to
808 % \lstpkg{}' \keyname{basicstyle} key (\emph{after} loading one of the three
809 % styles defined by \mlpkg{}) and also---this is important---^^A
810 % load the \pkg{fontenc} package with option \opt{T1}:
811 %^^A
812 % \begin{verbatim}
813 % \usepackage[T1]{fontenc}\end{verbatim}
814 %^^A
815 %
816 %
817 % \subsection{\mlpkg{}'s key-value interface}
818 %
819 % For each of the \mlpkg{} keys described below,
820 % the value assigned to it in the \mlsty{Matlab-editor} style is indicated
821 % on the right-hand side.
822 %^^A
823 % \begin{syntax}
824 %
825 % \item[0.1,\color{blue}]
826 % \rkeyname{mlkeywordstyle}|=|\meta{style}
827 %
828 % This key determines the style applied to \matlab{} keywords.
829 % The last token can be a one-parameter command,
830 % such as |\textbf| or |\underbar|.
831 %
832 % \item[0.1,\color{black}]
833 % \rkeyname{mllastelementstyle}|=|\meta{style}
834 %
835 % The |end| keyword has different meanings depending on the context in
836 % which it occurs:
837 % it may be used to close a code block (e.g.\ a while loop),
838 % or it may stand for the last element of an array.
839 % In the first case, it gets highlighted in the same style as the other
840 % \matlab{} keywords, like so: "end".
841 % In the other case, it gets highlighted like ``normal text'', like so:
842 % \overrideEnd.
843 % This key determines the style of this keyword in cases where it means
844 % ``last element''.
845 % The last token can be a one-parameter command,
846 % such as |\textbf| or |\underbar|.
847 %
848 % \item[0.1,false]
849 % \rkeyname{mloverride}|=|\meta{\alternative{true,false}}
850 % \syntaxor\rkeyname{mloverride}
851 %
852 % By default, in inline code, \mlpkg{} highlights the |end| keyword as
853 % the closing keyword (\emph{not} as the last-element keyword)
854 % and highlights the four class-definition identifiers as \matlab{}
855 % functions (\emph{not} as keywords), like so:
856 % "end", "events", "enumeration", "methods", and "properties".
857 % This key allows you to override the current context, so that those
858 % five context-sensitive keywords be typeset in the style of the
859 % alternative context, like so:
860 % \overrideEnd{},
861 % \overrideEvents{},
862 % \overrideEnumeration{},
863 % \overrideMethods{},
864 % \overrideProperties{}.
865 %
866 % \item[0.1,{\color[RGB]{160,32,240}}]
867 % \rkeyname{mlstringstyle}|=|\meta{style}
868 %
869 % This key determines the style applied to \matlab{} quoted and unquoted
870 % strings.
871 % The last token can be a one-parameter command,
872 % such as |\textbf| or |\underbar|.
873 %
874 % \item[0.1,{\color[RGB]{34,139,34}}]
875 % \rkeyname{mlcommentstyle}|=|\meta{style}
876 %
877 % This key determines the style applied to \matlab{} to-end-of-line and
878 % block comments.
879 % The last token can be a one-parameter command,
880 % such as |\textbf| or |\underbar|.
881 %
882 % \item[0.1,{\bfseries\color[RGB]{34,139,34}}]
883 % \rkeyname{mlsectiontitlestyle}|=|\meta{style}
884 %
885 % This key determines the style applied to \matlab{} section titles.
886 % The last token can be a one-parameter command,
887 % such as |\textbf| or |\underbar|.
888 %
889 % \item[0.1,false]
890 % \rkeyname{mlshowsectionrules}|=|\meta{\alternative{true,false}}
891 % \syntaxor\rkeyname{mlshowsectionrules}
892 %
893 % This key determines whether an horizontal rule gets printed above each
894 % \matlab{} section title.
895 %
896 % \item[0.1,.05]
897 % \rkeyname{mlsectionrulethickness}|=|\meta{number}
898 %
899 % This key determines the thickness of the horizontal rule above each
900 % \matlab{} section title.
901 % The resulting thickness corresponds to the product of the value passed
902 % to this key and the length value of |\baselineskip|.
903 %
904 % \item[0.1,black!15]
905 % \rkeyname{mlsectionrulecolor}|=|\meta{color}
906 %
907 % This key determines the color of the horizontal rule shown above each
908 % \matlab{} section title.
909 %
910 % \item[0.1,{\color[RGB]{178,140,0}}]
911 % \rkeyname{mlsyscomstyle}|=|\meta{style}
912 %
913 % This key determines the style applied to \matlab{} system commands.
914 % The last token can be a one-parameter command,
915 % such as |\textbf| or |\underbar|.
916 %
917 % \item[0.1]
918 % \rkeyname{mlsharedvars}|=|\meta{list of variables}
919 % \item[0.1]
920 % \rkeyname{mlmoresharedvars}|=|\meta{list of variables}
921 % \item[0.1]
922 % \rkeyname{mldeletesharedvars}|=|\meta{list of variables}
923 % \item[0.1,{\color[RGB]{0,163,163}}]
924 % \rkeyname{mlsharedvarstyle}|=|\meta{style}
925 %
926 % The first three of these four keys allow you to define, add, or remove
927 % (respectively) \matlab{} variables with shared scope.
928 % The last one determines the style applied to such variables;
929 % the last token can be a one-parameter command,
930 % such as |\textbf| or |\underbar|.
931 %
932 % \item[0.1]
933 % \rkeyname{mlunquotedstringdelim}|={|^^A
934 % \meta{opening delimiter}|}{|\meta{closing delimiter}|}|
935 %
936 % This key allows you to define delimiters
937 % (possibly composed of multiple characters)
938 % for highlighting unquoted strings;
939 % the delimiters themselves do not get printed in the output.
940 % Be aware that the special characters |{}#%\| must be escaped with a
941 % backslash (see item~5 in subsection~4.1 of the
942 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}).
943 % Note that this key is only a tentative solution;
944 % automatic highlighting of unquoted strings is a planned feature for the
945 % next release of \mlpkg{}, which should make this key obsolete.
946 %
947 % \item[0.1,{\rmfamily\itshape\color[RGB]{209,0,86}}]
948 % \rkeyname{mlplaceholderstyle}|=|\meta{style}
949 %
950 % This key determines the style applied to placeholders in code snippets.
951 % The last token can be a one-parameter command,
952 % such as |\textbf| or |\underbar|.
953 %
954 % \item[0.2,true]
955 % \rkeyname{mlscaleinline}|=|\meta{\alternative{true,false}}
956 % \syntaxor\rkeyname{mlscaleinline}
957 %
958 % If this key is set, any font-size specification in the basic style is
959 % overriden, and inline \matlab{} code is scaled to it surroundings;
960 % in other words, the font size of inline \matlab{} code is made to match
961 % the local font size.
962 %
963 % \item[0.2,false]
964 % \rkeyname{mlonlyheader}|=|\meta{\alternative{true,false}}
965 % \syntaxor\rkeyname{mlonlyheader}
966 %
967 % If this key is set, output is dropped after the first block of
968 % contiguous line comments, which normally corresponds to the function's
969 % header, if any.
970 %
971 % \end{syntax}
972 %
973 %
974 % \section{Tips and tricks}
975 %
976 % Here is a list of recommendations^^A
977 % ---some more opinionated than others.
978 % \paragraph{Stick with the \mllng{} language.}
979 % Defining a \lstpkg{} language based on \mllng{} is discouraged,
980 % for the following reason:
981 % \mlpkg{} performs some necessary housekeeping tasks at the beginning and
982 % end of each listing, but only under the condition that the name of the
983 % language used by the listing be \mllng{};
984 % therefore, \matlab{} listings are unlikely to get correctly highlighted if
985 % the language name differs from \mllng{}.
986 %
987 % \paragraph{Define your own style.}
988 % For maintainability reasons, if you're not completely satisfied with any of
989 % the predefined styles, you should define your own \lstpkg{} style.
990 % You can even base your custom style on one of the predefined styles and
991 % tweak it (see subsection~4.5 in the
992 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}).
993 %
994 % \paragraph{Load the base language/style first; customize later.}
995 % If you want to customize the appearance of your \matlab{} listings,
996 % you should use \lstpkg{}' \keyname{language} key or \keyname{style} key
997 % before using any other (\lstpkg{} or \mlpkg{}) key,
998 % because loading a language or a style ``too late'' has the potential to
999 % wipe out most of the current settings.
1000 %
1001 % \paragraph{Define macros for recurring placeholders.}
1002 % For maintainability reasons, you should define macros for oft-used
1003 % placeholders, e.g.
1004 %^^A
1005 % \begin{verbatim}
1006 % \newcommand\phcond{\mlplaceholder{condition}}\end{verbatim}
1007 %
1008 % \paragraph{For more highlights, use \lstpkg{}' \keyname{emph} key}
1009 % If you want to highlight some identifiers in \matlab{} listings, use
1010 % \lstpkg{}' \keyname{emph} key. Do \emph{not} use \lstpkg{}'
1011 % \keyname{keywords} or \keyname{morekeywords} keys.
1012 %
1013 % \paragraph{Don't copy \& paste!}
1014 % Do not encourage your readers to copy listings from their PDF viewer and
1015 % then paste them in the \matlab{} editor.
1016 % Unfortunately, it simply is \emph{not} a reliable way of distributing code,
1017 % for at least three reasons:
1018 %^^A
1019 % \begin{itemize}
1020 % \item copying listings than span multiple pages of a PDF document is
1021 % tedious and error-prone;
1022 % \item the results of copying content from a PDF for
1023 % subsequent pasting vary widely from one PDF viewer to another;
1024 % \item line breaks introduced by \lstpkg{} for typesetting a \matlab{}
1025 % listing may translate to invalid \matlab{} syntax, if copied and pasted
1026 % \emph{verbatim}.
1027 % \end{itemize}
1028 %
1029 % \paragraph{Typesetting a vertically centered tilde}
1030 % Unfortunately, not all fonts typeset the tilde character ("~") vertically
1031 % centered---as it is in the \matlab{} editor.
1032 % Be aware that, if you set a font for your \matlab{} listings
1033 % (via \lstpkg{}' \keyname{basicstyle} key) that is different from \mlpkg{}'s
1034 % default (a scaled-down version of Bera Mono), tilde characters occuring in
1035 % your listings may get typeset vertically off-center.
1036 % Because a good, font-independent workaround seems out of reach,
1037 % I refer you to \url{http://tex.stackexchange.com/q/312/21891},
1038 % where you will find a list of ad-hoc solutions.
1039 %
1040 % \paragraph{Avoid literate replacements like the plague!}
1041 % The \pkg{mcode} package predefines so-called ``literate replacements''
1042 % (see subsection~5.4 in the
1043 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}),
1044 % e.g.\ for printing~``\(\leq\)'' in place of each instance of~``"<="''.
1045 % I deliberately chose not to define any such literate replacements in
1046 % \mlpkg{} because I think that, rather than improving code readability,
1047 % they have a potential to confuse and mislead your readers.
1048 % In particular, newcomers to the programming language may not immediately
1049 % realize that those symbols are not part of the language's syntax;
1050 % they may ascribe literal meaning to them and attempt to reproduce them in
1051 % their editor or IDE.
1052 % How counterproductive!
1053 % Of course, if you insist, you can still define your own literate
1054 % replacements.
1055 %
1056 %
1057 % \part{Miscellaneous}
1058 %
1059 % \section{To-do list}
1060 %
1061 % \paragraph{Automatic highlighting of unquoted strings}
1062 % In the current version of \mlpkg{}, unquoted strings will only be
1063 % highlighted as strings if you delimit them with custom delimiters
1064 % (defined via the \rkeyname{mlunquotedstringdelim} key).
1065 % However, I have plans to implement an automatic approach in a future
1066 % release.
1067 % Note that this feature will make the \rkeyname{mlunquotedstringdelim} key
1068 % obsolete.
1069 %
1070 % \paragraph{Increased support for \octave{}'s syntax}
1071 % Support for \octave{}'s idiosyncratic syntax---^^A
1072 % e.g. |endif| and |endwhile| keywords---^^A
1073 % will be added in a future release of \mlpkg{}.
1074 %
1075 %
1076 % \section{Missing features and known issues}
1077 %
1078 % Although \mlpkg{} does a reasonably good job at replicating the syntax
1079 % highlighting performed by the \matlab{} editor, some problems remain.
1080 % Here is a list of known, currently unresolved problems.
1081 %
1082 % \paragraph{No automatic highlighting of variables with shared scope}
1083 % Unfortunately, automatic highlighting of variables with shared scope
1084 % would require multiple passes, which the \lstpkg{} package cannot do.
1085 % However, I believe that the number of variables in your \matlab{} code
1086 % should be small enough^^A
1087 % ---otherwise, your \matlab{} code is probably not sound!---^^A
1088 % that you can afford to highlight those variables manually, if you insist on
1089 % highlighting them at all.
1090 %
1091 % \paragraph{No highlighting of unterminated strings}
1092 % Because \lstpkg{} cannot look very far ahead, I haven't found an easy way of
1093 % checking whether an opening string delimiter is missing a matching (closing)
1094 % string delimiter on the same line.
1095 %
1096 % \paragraph{Illegal syntax tends to yield incorrect syntax highlighting}
1097 % For example, the \matlab{} editor would highlight the |end| keyword in the
1098 % listing below, not as closing keyword ("end"), but as last-element keyword
1099 % (\overrideEnd{}).
1100 %^^A
1101 % \begin{lstsample}{}{\lstset{style=nonbnoframe}}
1102 % \begin{lstlisting}[
1103 % style=Matlab-editor,
1104 % basicstyle=\mlttfamily,
1105 % numbers=none]
1106 % if=end
1107 % \end{lstlisting}
1108 % \end{lstsample}
1109 %
1110 % \paragraph{Some section titles fail to be highlighted as such}
1111 % In \matlab{}, a line containing only ``\texttt{\%\%}'' and blank
1112 % characters is a section title.
1113 % \mlpkg{} incorrectly highlights such a line in comment style.
1114 %^^A
1115 % \begin{lstsample}{}{\lstset{style=nonbnoframe}}
1116 % \begin{lstlisting}[
1117 % style=Matlab-editor,
1118 % numbers=none,
1119 % basicstyle=\mlttfamily,
1120 % numbers=none]
1121 % %% This is a section title
1122 % % and so is the next line
1123 % %%
1124 % % but it gets highlighted
1125 % % like a comment.
1126 % \end{lstlisting}
1127 % \end{lstsample}
1128 %
1129 % \paragraph{\lstpkg{}' \keyname{keespaces} key messes up section-title rules}
1130 % If both \lstpkg{}' \keyname{keepspaces} and \mlpkg{}'s
1131 % \rkeyname{mlshowsectionrules} are set, section titles that start by some
1132 % white space get pushed to the right.
1133 %^^A
1134 % \begin{lstsample}{}{\lstset{style=nonbnoframe}}
1135 % \begin{lstlisting}[
1136 % style=Matlab-editor,
1137 % basicstyle=\mlttfamily,
1138 % numbers=none,
1139 % keepspaces,
1140 % mlshowsectionrules]
1141 % %% the rule gets pushed to the right...
1142 % \end{lstlisting}
1143 % \end{lstsample}
1144 %
1145 % \paragraph{``Runaway'' block comments end prematurely (in some cases)}
1146 % \matlab{} requires opening and closing delimiters of block comments to each
1147 % be on a line on its own, without any visible character, but \mlpkg{}
1148 % incorrectly considers block comments closed even in some cases where this
1149 % rule is infringed.
1150 % For example, in the listing below, the \matlab{} editor would typeset
1151 % "a = 1" in comment style.
1152 %^^A
1153 % \begin{lstsample}{}{\lstset{style=nonbnoframe}}
1154 % \begin{lstlisting}[
1155 % style=Matlab-editor,
1156 % basicstyle=\mlttfamily,
1157 % numbers=none]
1158 % %{
1159 % "runaway"
1160 % block
1161 % comment %}
1162 % a = 1
1163 % \end{lstlisting}
1164 % \end{lstsample}
1165 %
1166 %
1167 % \section{Bug reports and feature suggestions}
1168 %
1169 % The development version of \mlpkg{} is currently hosted on Bitbucket at
1170 % \href{http://bitbucket.org/Jubobs/matlab-prettifier/}
1171 % {Jubobs/matlab-prettifier}.
1172 % If you find an issue in \mlpkg{} that this manual does not mention,
1173 % if you would like to see a feature implemented in the package,
1174 % or if you can think of ways in which the \mlpkg{} documentation could be
1175 % improved, please open a ticket in the Bitbucket repository's issue tracker;
1176 % alternatively, you can send me an email at
1177 % \href{mailto:[email protected]}
1178 % {[email protected]}
1179 %
1180 %
1181 % \section{Acknowledgments}
1182 % Thanks to the developers of the \lstpkg{} package,
1183 % without which \mlpkg{} would never have existed.
1184 % I'm also in debt to many
1185 % \href{http://tex.stackexchange.com}{TeX.SX} users for their help,
1186 % encouragements, and suggestions.
1187 % Thanks in particular to David Carlisle, Marco Daniel,
1188 % Enrico Gregorio (egreg), Harish Kumar, Heiko Oberdiek, and Robert Schlicht.
1189 % Thanks also to the good people at \href{http://www.ctan.org}{CTAN}
1190 % for hosting the package.
1191 %
1192 %
1193 % \makeatletter
1194 % \def\index@prologue{\part{Index}\markboth{Index}{Index}}
1195 % \makeatother
1196 % \StopEventually{^^A
1197 % \clearpage^^A
1198 % \PrintChanges^^A
1199 % \setcounter{IndexColumns}{2}^^A
1200 % \PrintIndex^^A
1201 % }
1202 %
1203 %
1204 % \part{Implementation}
1205 %
1206 % Be aware that, for ``namespacing'', the \mlpkg{} package uses, not a prefix,
1207 % but the ``|mlpr|''~suffix (preceded by an |@| character) throughout.
1208 %
1209 %
1210 % \section{Preliminary checks}
1211 %
1212 % \begin{macro}{\lstoptcheck@mlpr}
1213 % Because the \lstpkg{} options \opt{noaspects}, \opt{0.21}, and
1214 % \opt{savemem} are incompatible with \pkg{matlab-prettifier}, checking
1215 % whether the \lstpkg{} package has been loaded with any of those options is
1216 % a good idea; if so, we should issue an error.
1217 % This macro checks whether \lstpkg{} was loaded with a given option
1218 % and, if so, throws an error.
1219 % \begin{macrocode}
1220 \newcommand\lstoptcheck@mlpr[1]
1221 {%
1222 \@ifpackagewith{listings}{#1}%
1223 {
1224 \PackageError{matlab-prettifier}%
1225 {incompatible listings' option #1}%
1226 {%
1227 Make sure the `listings' package
1228 doesn't get loaded with option `#1'%
1229 }
1230 }
1231 {}
1232 }
1233 % \end{macrocode}
1234 % \end{macro}
1235 % We now use this macro to make sure that none of the problematic \lstpkg{}
1236 % options has been passed to \lstpkg{} during an earlier loading of that
1237 % package.
1238 % \begin{macrocode}
1239 \lstoptcheck@mlpr{noaspects}
1240 \lstoptcheck@mlpr{0.21}
1241 \lstoptcheck@mlpr{savemem}
1242 % \end{macrocode}
1243 %
1244 %
1245 % \section{Package options}
1246 %
1247 % \paragraph{Framed listings}
1248 % \begin{macro}{\ifframed@mlpr@}
1249 % This option draws a frame around each listing by default.
1250 % \begin{macrocode}
1251 \newif\ifframed@mlpr@
1252 \DeclareOption{framed}{\framed@mlpr@true}
1253 % \end{macrocode}
1254 % \end{macro}
1255 %
1256 % \paragraph{Numbered lines}
1257 % \begin{macro}{\ifnumbered@mlpr@}
1258 % This option prints line numbers to the left of each listing by default.
1259 % \begin{macrocode}
1260 \newif\ifnumbered@mlpr@
1261 \DeclareOption{numbered}{\numbered@mlpr@true}
1262 % \end{macrocode}
1263 % \end{macro}
1264 %
1265 % \paragraph{Draft}
1266 % This option is simply passed to \lstpkg{}.
1267 % \begin{macrocode}
1268 \DeclareOption{draft}{\PassOptionsToPackage{\CurrentOption}{listings}}
1269 % \end{macrocode}
1270 %
1271 % \paragraph{Final}
1272 % This option is simply passed to \lstpkg{}.
1273 % \begin{macrocode}
1274 \DeclareOption{final}{\PassOptionsToPackage{\CurrentOption}{listings}}
1275 % \end{macrocode}
1276 %
1277 % \paragraph{Discard undefined options}
1278 % We discard any other option passed to \mlpkg{} by the user
1279 % and issue a warning.
1280 % \begin{macrocode}
1281 \DeclareOption*%
1282 {%
1283 \OptionNotUsed
1284 \PackageWarning{matlab-prettifier}{Unknown `\CurrentOption' option}
1285 }
1286 % \end{macrocode}
1287 % \paragraph{Process options}
1288 % \begin{macrocode}
1289 \ProcessOptions\relax
1290 % \end{macrocode}
1291 %
1292 %
1293 % \section{Required packages}
1294 %
1295 % The \mlpkg{} package require three packages without any package option:
1296 % the \pkg{textcomp} package, in order to use \lstpkg{}' \keyname{upquote}
1297 % key;
1298 % the \pkg{xcolor} package, in order to color our \matlab{} code;
1299 % and, of course, the \lstpkg{} package.
1300 % \begin{macrocode}
1301 \RequirePackage{textcomp}[2005/09/27]
1302 \RequirePackage{xcolor}[2007/01/21]
1303 \RequirePackage{listings}[2013/08/26]
1304 % \end{macrocode}
1305 %
1306 %
1307 % \section{Definition of the \texorpdfstring{\mllng}{Matlab-pretty} language}
1308 %
1309 % \paragraph{Language name}
1310 % \begin{macro}{\language@mlpr}
1311 % To avoid code duplication in this package file, we define a macro that
1312 % expands to the name of our new language, \mllng{}.
1313 % \begin{macrocode}
1314 \newcommand\language@mlpr{Matlab-pretty}
1315 % \end{macrocode}
1316 % \end{macro}
1317 % \begin{macro}{\languageNormedDefd@mlpr}
1318 % However, because \lstpkg{} ``normalizes'' language names internally,
1319 % we will also need to define a macro that expands to the normalized name of
1320 % the new language.
1321 % \begin{macrocode}
1322 \expandafter\lst@NormedDef\expandafter\languageNormedDefd@mlpr%
1323 \expandafter{\language@mlpr}
1324 % \end{macrocode}
1325 % \end{macro}
1326 %
1327 % \paragraph{Language definition}
1328 % We can now define our new \lstpkg{} language, using some |\expandafter|
1329 % trickery on |\lstdefinelanguage|.
1330 % \begin{macrocode}
1331 \expandafter\expandafter\expandafter\lstdefinelanguage\expandafter%
1332 {\language@mlpr}
1333 {%
1334 % \end{macrocode}
1335 %
1336 % \paragraph{Case sensitivity}
1337 % \matlab{} is a case-sensitive language.
1338 % \begin{macrocode}
1339 sensitive=true,
1340 % \end{macrocode}
1341 %
1342 % \paragraph{Forbidden characters in identifiers}
1343 % By default, \lstpkg{} allows ``\$'' and ``@'' to occur in identifiers,
1344 % but those characters are not valid \matlab{} identifiers.
1345 % \begin{macrocode}
1346 alsoother={\$@},
1347 % \end{macrocode}
1348 %
1349 % \paragraph{Character-table adjustments}
1350 % In order to keep track of the context, we need to modify the character
1351 % table a bit.
1352 % \begin{macrocode}
1353 MoreSelectCharTable=\MoreSelectCharTable@mlpr,
1354 % \end{macrocode}
1355 %
1356 % \paragraph{Keywords}
1357 %
1358 % The keywords defined below are based on the list returned by the
1359 % \matlabver{} "iskeyword" function and the four class-definition keywords^^A
1360 % ---which are omitted by the "iskeyword" function.
1361 % Because different \matlab{} keywords affect the context in different ways,
1362 % we use several classes of \pkg{listings} keywords to handle them.
1363 %
1364 % The following keywords open a block unrelated to class definition.
1365 % \begin{macrocode}
1366 morekeywords=[1]%
1367 {%
1368 for,
1369 if,
1370 otherwise,
1371 parfor,
1372 spmd,
1373 switch,
1374 try,
1375 while,
1376 },
1377 keywordstyle=[1]\processOpRegKW@mlpr,
1378 % \end{macrocode}
1379 % Most of the following keywords (nicknamed ``middle'' keywords herein) can
1380 % only occur within a block opened by the keywords listed above^^A
1381 % ---"function" and "return" are exceptions, but, as far as I can tell,
1382 % seem to have the same effects on syntax highlighting as the others---^^A
1383 % and are unrelated to class definition.
1384 % \begin{macrocode}
1385 morekeywords=[2]%
1386 {%
1387 break,
1388 case,
1389 catch,
1390 continue,
1391 else,
1392 elseif,
1393 function,
1394 return,
1395 },
1396 keywordstyle=[2]\processMidKW@mlpr,
1397 % \end{macrocode}
1398 % The following two keywords are ``standalone'';
1399 % they don't open or close any block.
1400 % \begin{macrocode}
1401 morekeywords=[3]%
1402 {%
1403 global,
1404 persistent,
1405 },
1406 keywordstyle=[3]\processStdaKW@mlpr,
1407 % \end{macrocode}
1408 % The "classdef" keyword interacts with other keywords in a unique fashion;
1409 % therefore, we dedicate a whole class of \lstpkg{} keywords to it.
1410 % \begin{macrocode}
1411 morekeywords=[4]{classdef},
1412 keywordstyle=[4]\processClassdefKW@mlpr,
1413 % \end{macrocode}
1414 % We dedicate a class of \lstpkg{} keywords to the four \matlab{} keywords
1415 % that only occur within a class-definition block,
1416 % namely \overrideEvents{}, \overrideEnumeration{}, \overrideMethods{},
1417 % and \overrideProperties{}.
1418 % \begin{macrocode}
1419 morekeywords=[5]%
1420 {%
1421 enumeration,
1422 events,
1423 methods,
1424 properties,
1425 },
1426 keywordstyle=[5]\processMidClassdefKW@mlpr,
1427 % \end{macrocode}
1428 % The |end| keyword has a very peculiar behavior and deserves its own keyword
1429 % class.
1430 % \begin{macrocode}
1431 morekeywords=[6]{end},
1432 keywordstyle=[6]\processEndKW@mlpr,
1433 % \end{macrocode}
1434 %
1435 % \paragraph{Strings}
1436 % We simply use \lstpkg{}' built-in mechanism for highlighting \matlab{}
1437 % quoted string\ldots with a twist; more details follow.
1438 % \begin{macrocode}
1439 morestring=[m]',
1440 stringstyle=\processString@mlpr,
1441 % \end{macrocode}
1442 %
1443 % \paragraph{Comments \& section titles}
1444 % Delimiters for to-end-of-line and block comments are defined below.
1445 % \begin{macrocode}
1446 morecomment=[l]\%,
1447 morecomment=[n]{\%\{\^^M}{\%\}\^^M},
1448 commentstyle=\commentStyle@mlpr,
1449 % \end{macrocode}
1450 % The line-continuation token ("..."), which starts a to-end-of-line comment,
1451 % is treated separately.
1452 % \begin{macrocode}
1453 moredelim=**[il][\processDotDotDot@mlpr]{...},
1454 % \end{macrocode}
1455 % Section titles, as special comments that get highlighted in a style
1456 % different to that of regular comments, must also be treated separately.
1457 % \begin{macrocode}
1458 moredelim=[l][\processSectionTitle@mlpr]{\%\%\ },
1459 % \end{macrocode}
1460 %
1461 % \paragraph{System commands}
1462 % System commands are handled in a straightforward manner by an |l|-type
1463 % delimiter.
1464 % \begin{macrocode}
1465 moredelim=[l][\syscomStyle@mlpr]!,
1466 % \end{macrocode}
1467 %
1468 % \paragraph{Required \lstpkg{} aspects}
1469 % We now only need to specify the required \lstpkg{} ``aspects''.
1470 % \begin{macrocode}
1471 }[
1472 keywords,
1473 strings,
1474 comments,
1475 ]
1476 % \end{macrocode}
1477 %
1478 %
1479 % \section{State variables}
1480 % We define a number of \TeX{} counters and switches that will be used as
1481 % ``state variables'', to keep track of the context.
1482 %
1483 % \paragraph{Counters}
1484 % \begin{macro}{\netBracketCount@mlpr}
1485 % This counter is used to keep a net running count of opening and closing
1486 % brackets---roughly speaking.
1487 % When an opening bracket---be it round, square or curly---is encountered,
1488 % the counter is incremented;
1489 % conversely, when a closing bracket is encountered, the counter is
1490 % decremented.
1491 % I write ``roughly speaking'', because that counter gets reset on some
1492 % occasions; more details follow.
1493 % \begin{macrocode}
1494 \newcount\netBracketCount@mlpr
1495 % \end{macrocode}
1496 % \end{macro}
1497 % \begin{macro}{\blkLvl@mlpr}
1498 % This counter counter is used to keep track of the block nesting level.
1499 % \begin{macrocode}
1500 \newcount\blkLvl@mlpr
1501 % \end{macrocode}
1502 % \end{macro}
1503 % \begin{macro}{\blkLvlAtClassdef@mlpr}
1504 % This counter is used to keep track of the block nesting level at which the
1505 % last "classdef" keyword occured.
1506 % \begin{macrocode}
1507 \newcount\blkLvlAtClassdef@mlpr
1508 % \end{macrocode}
1509 % \end{macro}
1510 %
1511 % \paragraph{Switches}
1512 % \begin{macro}{\ifClosingEndKW@mlpr@}
1513 % This switch determines whether the |end| keyword acts as a closing keyword
1514 % or as last-element keyword in the current context.
1515 % \begin{macrocode}
1516 \newif\ifClosingEndKW@mlpr@ \ClosingEndKW@mlpr@true
1517 % \end{macrocode}
1518 % \end{macro}
1519 % \begin{macro}{\ifInClassdef@mlpr@}
1520 % This switch determines whether we're within a class-definition block or not.
1521 % \begin{macrocode}
1522 \newif\ifInClassdef@mlpr@ \InClassdef@mlpr@false
1523 % \end{macrocode}
1524 % \end{macro}
1525 % \begin{macro}{\ifInStr@mlpr@}
1526 % This switch determines whether we're inside a string or not.
1527 % \begin{macrocode}
1528 \newif\ifInStr@mlpr@ \InStr@mlpr@false
1529 % \end{macrocode}
1530 % \end{macro}
1531 % \begin{macro}{\ifVisCharOccured@mlpr@}
1532 % This switch is used to keep track of whether visible characters have
1533 % occured on the current line.
1534 % \begin{macrocode}
1535 \newif\ifVisCharOccured@mlpr@\VisCharOccured@mlpr@false
1536 % \end{macrocode}
1537 % \end{macro}
1538 % \begin{macro}{\ifInSecTitle@mlpr@}
1539 % This switch determines whether we're inside a section title or not.
1540 % \begin{macrocode}
1541 \newif\ifInSecTitle@mlpr@ \InSecTitle@mlpr@false
1542 % \end{macrocode}
1543 % \end{macro}
1544 % \begin{macro}{\ifDroppingOutput@mlpr@}
1545 % This switch determines whether we're passed the first contiguous block of
1546 % line comments (function header).
1547 % \begin{macrocode}
1548 \newif\ifDroppingOutput@mlpr@\DroppingOutput@mlpr@false
1549 % \end{macrocode}
1550 % \end{macro}
1551 %
1552 % \paragraph{Helper macros for resetting state variables}
1553 % The following macros are used to reset counters and switches.
1554 % \begin{macro}{\resetEndKW@mlpr}
1555 % This macro restores the |end| keyword as a closing keyword.
1556 % \begin{macrocode}
1557 \newcommand\resetEndKW@mlpr
1558 {%
1559 \global\ClosingEndKW@mlpr@true%
1560 \global\netBracketCount@mlpr=0%
1561 }
1562 % \end{macrocode}
1563 % \end{macro}
1564 % \begin{macro}{\resetClassdefKW@mlpr}
1565 % This macro reinitializes state variables related to class definition.
1566 % \begin{macrocode}
1567 \newcommand\resetClassdefKW@mlpr
1568 {%
1569 \global\InClassdef@mlpr@false%
1570 \global\blkLvl@mlpr=0%
1571 \global\blkLvlAtClassdef@mlpr=0%
1572 }
1573 % \end{macrocode}
1574 % \end{macro}
1575 %
1576 %
1577 % \section{Processing of syntactic elements}
1578 %
1579 % (The overarching algorithm is not documented here;
1580 % in a future release, perhaps.)
1581 %
1582 % \paragraph{Processing of brackets}
1583 % An opening and or a closing brackets occuring in a \matlab{} listing affects
1584 % the context;
1585 % for instance, an |end| keyword is always interpreted as a closing keyword if
1586 % it is immediately preceded by a closing bracket, no matter what comes
1587 % before that.
1588 % To keep track of the context, we must update our state variables every time
1589 % a bracket is encountered.
1590 %
1591 % \begin{macro}{\MoreSelectCharTable@mlpr}
1592 % This macro, which is passed to \lstpkg{}' \keyname{MoreSelectCharTable} key
1593 % in the definition of \mllng{}, allows us to dictate what happens when a
1594 % bracket or a semicolon is encountered.
1595 % \begin{macrocode}
1596 \newcommand\MoreSelectCharTable@mlpr
1597 {%
1598 % \end{macrocode}
1599 %
1600 % \begin{macro}{\roundBktOp@mlpr}
1601 % We store the original definition of ``|(|'' from the default character
1602 % table in a dedicated macro and modify the behavior of that character.
1603 % \begin{macrocode}
1604 \processOpenBracket@mlpr{`(}{\roundBktOp@mlpr}%
1605 % \end{macrocode}
1606 % \end{macro}
1607 %
1608 % \begin{macro}{\squareBktOp@mlpr}
1609 % We store the original definition of ``|[|'' from the default character
1610 % table in a dedicated macro and modify the behavior of that character.
1611 % \begin{macrocode}
1612 \processOpenBracket@mlpr{`[}{\squareBktOp@mlpr}%
1613 % \end{macrocode}
1614 % \end{macro}
1615 %
1616 % \begin{macro}{\curlyBktOp@mlpr}
1617 % We store the original definition of ``|{|'' from the default character
1618 % table in a dedicated macro and modify the behavior of that character.
1619 % \begin{macrocode}
1620 \processOpenBracket@mlpr{`\{}{\curlyBktOp@mlpr}%
1621 % \end{macrocode}
1622 % \end{macro}
1623 %
1624 % \begin{macro}{\roundBktCl@mlpr}
1625 % We store the original definition of ``|)|'' from the default character
1626 % table in a dedicated macro and modify the behavior of that character.
1627 % \begin{macrocode}
1628 \processCloseBracket@mlpr{`)}{\roundBktCl@mlpr}%
1629 % \end{macrocode}
1630 % \end{macro}
1631 %
1632 % \begin{macro}{\squareBktCl@mlpr}
1633 % We store the original definition of ``|]|'' from the default character
1634 % table in a dedicated macro and modify the behavior of that character.
1635 % \begin{macrocode}
1636 \processCloseBracket@mlpr{`]}{\squareBktCl@mlpr}%
1637 % \end{macrocode}
1638 % \end{macro}
1639 %
1640 % \begin{macro}{\curlyBktCl@mlpr}
1641 % We store the original definition of ``|}|'' from the default character
1642 % table in a dedicated macro and modify the behavior of that character.
1643 % \begin{macrocode}
1644 \processCloseBracket@mlpr{`\}}{\curlyBktCl@mlpr}%
1645 % \end{macrocode}
1646 % \end{macro}
1647 %
1648 % \begin{macro}{\semicolon@mlpr}
1649 % We store the original definition of ``|;|'' from the default character
1650 % table in a dedicated macro and modify the behavior of that character.
1651 % \begin{macrocode}
1652 \processSemicolon@mlpr{`;}{\semicolon@mlpr}%
1653 % \end{macrocode}
1654 % \end{macro}
1655 % \begin{macrocode}
1656 }
1657 % \end{macrocode}
1658 % \end{macro}
1659 %
1660 % \begin{macro}{\processOpenBracket@mlpr}
1661 % This macro is used to ``hook into'' opening-bracket characters and update
1662 % state variables every time such a character is encountered in \lstpkg{}'
1663 % ``processing mode''.
1664 % \begin{macrocode}
1665 \newcommand\processOpenBracket@mlpr[2]
1666 {%
1667 \lst@DefSaveDef{#1}#2%
1668 {%
1669 #2%
1670 \ifnum\lst@mode=\lst@Pmode\relax%
1671 \global\ClosingEndKW@mlpr@false%
1672 \global\advance\netBracketCount@mlpr by \@ne%
1673 \fi
1674 }%
1675 }
1676 % \end{macrocode}
1677 % \end{macro}
1678 %
1679 % \begin{macro}{\processCloseBracket@mlpr}
1680 % This macro is used to ``hook into'' closing-bracket characters and update
1681 % state variables every time such a character is encountered in \lstpkg{}'
1682 % ``processing mode''.
1683 % \begin{macrocode}
1684 \newcommand\processCloseBracket@mlpr[2]
1685 {%
1686 \lst@DefSaveDef{#1}#2%
1687 {%
1688 #2%
1689 \ifnum\lst@mode=\lst@Pmode\relax%
1690 \ifClosingEndKW@mlpr@%
1691 \netBracketCount@mlpr=0%
1692 \else
1693 \global\advance\netBracketCount@mlpr by \m@ne%
1694 \ifnum\netBracketCount@mlpr>0%
1695 \else
1696 \global\ClosingEndKW@mlpr@true%
1697 \fi
1698 \fi
1699 \fi
1700 }%
1701 }
1702 % \end{macrocode}
1703 % \end{macro}
1704 %
1705 % \begin{macro}{\processSemicolon@mlpr}
1706 % This macro is used to ``hook into'' the semicolon character and update
1707 % state variables every time such a character is encountered in \lstpkg{}'
1708 % ``processing mode''.
1709 % \begin{macrocode}
1710 \newcommand\processSemicolon@mlpr[2]
1711 {%
1712 \lst@DefSaveDef{#1}#2%
1713 {%
1714 #2%
1715 \ifnum\lst@mode=\lst@Pmode\relax%
1716 \resetEndKW@mlpr%
1717 \fi
1718 }%
1719 }
1720 % \end{macrocode}
1721 % \end{macro}
1722 %
1723 % \paragraph{Processing of keywords}
1724 % The following macros are used for updating state variables every time a
1725 % keyword is encountered in \lstpkg{} ``processing mode''.
1726 %
1727 % \begin{macro}{\processOpRegKW@mlpr}
1728 % This macro updates state variables every time an opening keyword is
1729 % processed, and applies keyword style.
1730 % \begin{macrocode}
1731 \newcommand\processOpRegKW@mlpr
1732 {%
1733 \resetEndKW@mlpr%
1734 \global\advance\blkLvl@mlpr\@ne%
1735 \keywordStyle@mlpr%
1736 }
1737 % \end{macrocode}
1738 % \end{macro}
1739 %
1740 % \begin{macro}{\processMidKW@mlpr}
1741 % This macro updates state variables every time a ``middle'' keyword is
1742 % processed, and applies keyword style.
1743 % \begin{macrocode}
1744 \newcommand\processMidKW@mlpr
1745 {%
1746 \resetEndKW@mlpr%
1747 \keywordStyle@mlpr%
1748 }
1749 % \end{macrocode}
1750 % \end{macro}
1751 % \begin{macro}{\processStdaKW@mlpr}
1752 % As far as I can tell, ``standalone'' keywords and ``middle'' keywords
1753 % affect the context in the same way;
1754 % therefore, we simply reuse |\processMidKW@mlpr| here.
1755 % \begin{macrocode}
1756 \newcommand\processStdaKW@mlpr\processMidKW@mlpr
1757 % \end{macrocode}
1758 % \end{macro}
1759 % \begin{macro}{\processClassdefKW@mlpr}
1760 % This macro updates state variables every time the "classdef" keyword is
1761 % processed, and applies keyword style.
1762 % \begin{macrocode}
1763 \newcommand\processClassdefKW@mlpr
1764 {%
1765 \resetEndKW@mlpr%
1766 \global\InClassdef@mlpr@true%
1767 \global\blkLvlAtClassdef@mlpr=\blkLvl@mlpr%
1768 \global\advance\blkLvl@mlpr\@ne%
1769 \keywordStyle@mlpr%
1770 }
1771 % \end{macrocode}
1772 % \end{macro}
1773 % \begin{macro}{\processMidClassdefKW@mlpr}
1774 % This macro updates state variables every time one of the four keywords
1775 % that only occur within a class-definition block is processed, and applies
1776 % the appropriate style.
1777 % \begin{macrocode}
1778 \newcommand\processMidClassdefKW@mlpr
1779 {%
1780 \ifOverridecontext@mlpr@%
1781 \keywordStyle@mlpr%
1782 \else
1783 \ifInClassdef@mlpr@%
1784 \resetEndKW@mlpr%
1785 \global\advance\blkLvl@mlpr\@ne%
1786 \keywordStyle@mlpr%
1787 \fi
1788 \fi
1789 }
1790 % \end{macrocode}
1791 % \end{macro}
1792 % \begin{macro}{\processEndKW@mlpr}
1793 % This macro updates state variables every time the |end| keyword is
1794 % processed, and applies the appropriate style.
1795 % \begin{macrocode}
1796 \newcommand\processEndKW@mlpr
1797 {%
1798 \ifOverridecontext@mlpr@%
1799 \lastElemStyle@mlpr%
1800 \else
1801 \ifClosingEndKW@mlpr@%
1802 \ifnum\blkLvl@mlpr>0%
1803 \global\advance\blkLvl@mlpr\m@ne%
1804 \fi
1805 \ifnum\blkLvl@mlpr=\blkLvlAtClassdef@mlpr%
1806 \global\InClassdef@mlpr@false%
1807 \fi
1808 \keywordStyle@mlpr%
1809 \else
1810 \lastElemStyle@mlpr%
1811 \fi
1812 \fi
1813 }
1814 % \end{macrocode}
1815 % \end{macro}
1816 %
1817 % \paragraph{Processing of strings}
1818 % \begin{macro}{\processString@mlpr}
1819 % This macro records that a string has just started by setting the appropriate
1820 % switch, and applies string style.
1821 % \begin{macrocode}
1822 \newcommand\processString@mlpr
1823 {%
1824 \global\InStr@mlpr@true%
1825 \stringStyle@mlpr%
1826 }
1827 % \end{macrocode}
1828 % \end{macro}
1829 %
1830 % \paragraph{Processing of line-continuation tokens}
1831 % \begin{macro}{\processDotDotDot@mlpr}
1832 % This macro typesets the line-continuation token in the style of our
1833 % \matlab{} keywords,
1834 % prohibits any mode changes on the rest of the current line,
1835 % and applies comment style to the rest of the current line.
1836 % \begin{macrocode}
1837 \newcommand\processDotDotDot@mlpr
1838 {%
1839 \lst@CalcLostSpaceAndOutput%
1840 {\keywordStyle@mlpr...}%
1841 \lst@modetrue%
1842 \lst@Lmodetrue%
1843 \commentStyle@mlpr%
1844 }
1845 % \end{macrocode}
1846 % \end{macro}
1847 %
1848 % \paragraph{Processing of section titles}
1849 % First, we need to define a few length macros in order to draw the horizontal
1850 % rule that \matlab{} shows (by default) above each section title.
1851 % \begin{macro}{\emHeight@mlpr}
1852 % We will use this length to store the height of the ``M'' character in the
1853 % current font.
1854 % \begin{macrocode}
1855 \newlength\emHeight@mlpr
1856 % \end{macrocode}
1857 % \end{macro}
1858 % \begin{macro}{\jayDepth@mlpr}
1859 % We will use this length to store the depth of letter ``j'' in the current
1860 % font.
1861 % \begin{macrocode}
1862 \newlength\jayDepth@mlpr
1863 % \end{macrocode}
1864 % \end{macro}
1865 % \begin{macro}{\sectionRuleOffset@mlpr}
1866 % We will use this length to store the result of our calculations for the
1867 % vertical offset required.
1868 % \begin{macrocode}
1869 \newlength\sectionRuleOffset@mlpr
1870 % \end{macrocode}
1871 % \end{macro}
1872 % Let's proceed\ldots
1873 % \begin{macro}{\processSectionTitle@mlpr}
1874 % This macro is invoked when a |%%| delimiter is encountered.
1875 % \begin{macrocode}
1876 \newcommand\processSectionTitle@mlpr
1877 {%
1878 \ifInSecTitle@mlpr@%
1879 \sectionTitleStyle@mlpr%
1880 \else
1881 % \end{macrocode}
1882 % If visible characters have already been encountered before the |%%| on the
1883 % current line, this line is simply typeset as a to-end-of-line comment.
1884 % \begin{macrocode}
1885 \ifVisCharOccured@mlpr@%
1886 \commentStyle@mlpr%
1887 % \end{macrocode}
1888 % Otherwise, a section title starts here;
1889 % we update the relevant state variables and, if the
1890 % \rkeyname{mlshowsectionrules} key has been set, we draw a horizontal rule.
1891 % \begin{macrocode}
1892 \else % a section title is starting here
1893 \global\InSecTitle@mlpr@true%
1894 \resetEndKW@mlpr%
1895 \ifShowSectRules@mlpr@%
1896 \drawSectionRule@mlpr%
1897 \fi
1898 \sectionTitleStyle@mlpr%
1899 \fi
1900 \fi
1901 }
1902 % \end{macrocode}
1903 % \end{macro}
1904 % \begin{macro}{\drawSectionRule@mlpr}
1905 % This helper macro is used for drawing a horizontal rule just above the
1906 % current line.
1907 % \begin{macrocode}
1908 \newcommand\drawSectionRule@mlpr
1909 {%
1910 % \end{macrocode}
1911 % We measure the height of the ``M'' character and the depth of the ``j''
1912 % character, which we then use to calculate the required vertical offset.
1913 % \begin{macrocode}
1914 \setlength\emHeight@mlpr{\fontcharht\font`M}%
1915 \setlength\jayDepth@mlpr{\fontchardp\font`j}%
1916 \setlength\sectionRuleOffset@mlpr%
1917 {%
1918 \dimexpr.5\emHeight@mlpr%
1919 +.5\baselineskip%
1920 -.5\jayDepth@mlpr\relax%
1921 }%
1922 % \end{macrocode}
1923 % We now draw a rule as required (color and dimensions).
1924 % \begin{macrocode}
1925 \bgroup%
1926 \color{\sectionRuleColor@mlpr}%
1927 \makebox[0em][l]%
1928 {%
1929 \raisebox{\sectionRuleOffset@mlpr}[0pt][0pt]%
1930 {\rule{\lst@linewidth}{\sectionRuleRT@mlpr\baselineskip}}%
1931 }%
1932 \egroup%
1933 }
1934 % \end{macrocode}
1935 % \end{macro}
1936 %
1937 % \section{Hooking into \lstpkg{}' hooks}
1938 %
1939 % We apply some necessary patches in a number of \lstpkg{}' hooks;
1940 % but first, we define a few helper macros.
1941 %
1942 % \paragraph{Helper macros related to hooks}
1943 % \begin{macro}{\localFontSize@mlpr}
1944 % This macro will be used to save the current font size.
1945 % \begin{macrocode}
1946 \newcommand\localFontSize@mlpr{}
1947 % \end{macrocode}
1948 % \end{macro}
1949 % \begin{macro}{\localBaselineskip@mlpr}
1950 % This macro will be used to save the current value of |\baselineskip|.
1951 % \begin{macrocode}
1952 \newcommand\localBaselineskip@mlpr{}
1953 % \end{macrocode}
1954 % \end{macro}
1955 % \begin{macro}{\scaleInlineCode@mlpr}
1956 % This helper macro is for setting the font size of inline code to the local
1957 % font size (only if the \rkeyname{mlscaleinline} key is set).
1958 % \begin{macrocode}
1959 \newcommand\scaleInlineCode@mlpr
1960 {%
1961 \lst@ifdisplaystyle%
1962 \else
1963 \ifScaleInline@mlpr@%
1964 % \end{macrocode}
1965 % We save the values of the current font size and of |\baselineskip| into our
1966 % dedicated macros\ldots
1967 % \begin{macrocode}
1968 \let\localFontSize@mlpr\f@size%
1969 \let\localBaselineskip@mlpr\f@baselineskip%
1970 % \end{macrocode}
1971 % \ldots and we use the basic style but we update the font size.
1972 % \begin{macrocode}
1973 \expandafter\def\expandafter\lst@basicstyle\expandafter%
1974 {%
1975 \lst@basicstyle%
1976 \fontsize{\localFontSize@mlpr}{\localBaselineskip@mlpr}%
1977 \selectfont%
1978 }%
1979 \fi
1980 \fi
1981 }
1982 % \end{macrocode}
1983 % \end{macro}
1984 % \begin{macro}{\dropOutputAfterHeader@mlpr}
1985 % This macro detects when the first block (if any) of contiguous of line
1986 % comments (function header) ends and drops output thereafter.
1987 % \begin{macrocode}
1988 \newcommand\dropOutputAfterHeader@mlpr
1989 {%
1990 \ifonlyheader@mlpr@%
1991 \ifnum\lst@lineno>1%
1992 \lst@ifLmode%
1993 \else
1994 % \end{macrocode}
1995 % At this stage, the header has definitely ended.
1996 % If we've already begun dropping output, we don't do anything.
1997 % \begin{macrocode}
1998 \ifDroppingOutput@mlpr@%
1999 % \end{macrocode}
2000 % Otherwise, we begin dropping output now and we set the switch accordingly.
2001 % \begin{macrocode}
2002 \else
2003 \lst@EnterMode\lst@Pmode{}%
2004 \lst@BeginDropOutput\lst@Pmode%
2005 \fi
2006 \global\DroppingOutput@mlpr@true%
2007 % \end{macrocode}
2008 % \begin{macrocode}
2009 \fi
2010 \fi
2011 \fi
2012 }
2013 % \end{macrocode}
2014 % \end{macro}
2015 %
2016 % \paragraph{\hookname{InitVarsEOL}}
2017 % (See the
2018 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}
2019 % for more details on this hook.)
2020 % \begin{macro}{\addedToInitVarsEOL@mlpr}
2021 % We add this macro (initially empty) to \lstpkg{}'
2022 % \hookname{InitVarsEOL} hook.
2023 % \begin{macrocode}
2024 \newcommand\addedToInitVarsEOL@mlpr{}
2025 \lst@AddToHook{InitVarsEOL}{\addedToInitVarsEOL@mlpr}
2026 % \end{macrocode}
2027 % \end{macro}
2028 % \begin{macro}{\@ddedToInitVarsEOL@mlpr}
2029 % The |\addedToInitVarsEOL@mlpr| macro is let to this one under certain
2030 % conditions (more details follow).
2031 % \begin{macrocode}
2032 \newcommand\@ddedToInitVarsEOL@mlpr
2033 {%
2034 % \end{macrocode}
2035 % \lstpkg{}' built-in mechanism for handling \matlab{} string does not cover
2036 % the illegal case in which an opening string delimiter is not followed by
2037 % any matching (closing) string delimiter on the same line.
2038 % More specifically, \lstpkg{} incorrectly highlights such a broken string
2039 % literal as a bona-fide \matlab{} string.
2040 % We improve the situation somewhat, by only highlighting as a string the line
2041 % containing the unmatched opening delimiter, not the lines that follow it:
2042 % \begin{macrocode}
2043 \ifInStr@mlpr@%
2044 \global\InStr@mlpr@false%
2045 \lst@LeaveMode%
2046 \fi
2047 % \end{macrocode}
2048 % Clearly, at the very beginning of a line, we're not (not yet, anyway)
2049 % within a section title, and no visible character has yet occured on that
2050 % line.
2051 % \begin{macrocode}
2052 \global\InSecTitle@mlpr@false%
2053 \global\VisCharOccured@mlpr@false%
2054 }
2055 % \end{macrocode}
2056 % \end{macro}
2057 %
2058 % \paragraph{\hookname{EndGroup}}
2059 % (See the
2060 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}
2061 % for more details on this hook.)
2062 % \begin{macro}{\addedToEndGroup@mlpr}
2063 % We add this macro (initially empty) to \lstpkg{}'
2064 % \hookname{EndGroup} hook.
2065 % \begin{macrocode}
2066 \newcommand\addedToEndGroup@mlpr{}
2067 \lst@AddToHook{EndGroup}{\addedToEndGroup@mlpr}
2068 % \end{macrocode}
2069 % \end{macro}
2070 % \begin{macro}{\@ddedToEndGroup@mlpr}
2071 % The |\addedToEndGroup@mlpr| macro is let to this one under certain
2072 % conditions (more details follow).
2073 % If we were in a string before when \hookname{EndGroup} hook was called,
2074 % we're now exiting it;
2075 % therefore, the relevant switch must be reset.
2076 % \begin{macrocode}
2077 \newcommand\@ddedToEndGroup@mlpr{\global\InStr@mlpr@false}
2078 % \end{macrocode}
2079 % \end{macro}
2080 %
2081 % \paragraph{\hookname{PostOutput}}
2082 % (See the
2083 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}
2084 % for more details on this hook.)
2085 % \begin{macro}{\addedToPostOutput@mlpr}
2086 % We add this macro (initially empty) to \lstpkg{}'
2087 % \hookname{PostOutput} hook.
2088 % \begin{macrocode}
2089 \newcommand\addedToPostOutput@mlpr{}
2090 \lst@AddToHook{PostOutput}{\addedToPostOutput@mlpr}
2091 % \end{macrocode}
2092 % \end{macro}
2093 % \begin{macro}{\@ddedToPostOutput@mlpr}
2094 % The |\addedToPostOutput@mlpr| macro is let to this one under certain
2095 % conditions (more details follow).
2096 % If the last processed character was not white space
2097 % (this check is necessary if \lstpkg{}' \keyname{keepspaces} key is set),
2098 % we set the relevant switch.
2099 % \begin{macrocode}
2100 \newcommand\@ddedToPostOutput@mlpr
2101 {%
2102 \lst@ifwhitespace%
2103 \else
2104 \global\VisCharOccured@mlpr@true%
2105 \fi
2106 }
2107 % \end{macrocode}
2108 % \end{macro}
2109 %
2110 % \paragraph{\hookname{Output}}
2111 % (See the
2112 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}
2113 % for more details on this hook.)
2114 % \begin{macro}{\addedToOutput@mlpr}
2115 % We add this macro (initially empty) to \lstpkg{}'
2116 % \hookname{Output} hook.
2117 % \begin{macrocode}
2118 \newcommand\addedToOutput@mlpr{}
2119 \lst@AddToHook{Output}{\addedToOutput@mlpr}
2120 % \end{macrocode}
2121 % \end{macro}
2122 % \begin{macro}{\@ddedToOutput@mlpr}
2123 % The |\addedToOutput@mlpr| macro is let to this one under certain
2124 % conditions (more details follow).
2125 % If the \rkeyname{mlonlyheader} is set, we begin dropping output as soon as
2126 % we detect that the first contiguous block of line comments has been passed.
2127 % \begin{macrocode}
2128 \newcommand\@ddedToOutput@mlpr{\dropOutputAfterHeader@mlpr}
2129 % \end{macrocode}
2130 % \end{macro}
2131 %
2132 % \paragraph{\hookname{OutputOther}}
2133 % (See the
2134 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}
2135 % for more details on this hook.)
2136 % \begin{macro}{\addedToOutputOther@mlpr}
2137 % We add this macro (initially empty) to \lstpkg{}'
2138 % \hookname{OutputOther} hook.
2139 % \begin{macrocode}
2140 \newcommand\addedToOutputOther@mlpr{}
2141 \lst@AddToHook{OutputOther}{\addedToOutputOther@mlpr}
2142 % \end{macrocode}
2143 % \end{macro}
2144 % \begin{macro}{\@ddedToOutputOther@mlpr}
2145 % The |\addedToOutputOther@mlpr| macro is let to this one under certain
2146 % conditions (more details follow).
2147 % If the \rkeyname{mlonlyheader} is set, we begin dropping output as soon as
2148 % we detect that the first contiguous block of line comments has been passed.
2149 % \begin{macrocode}
2150 \newcommand\@ddedToOutputOther@mlpr{\dropOutputAfterHeader@mlpr}
2151 % \end{macrocode}
2152 % \end{macro}
2153 %
2154 % \paragraph{\hookname{PreInit}}
2155 % (See the
2156 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}
2157 % for more details on this hook.)
2158 % Because the |\lst@AddToHook| affects hooks globally
2159 % (i.e.\ for all listings),
2160 % we must apply our patches only when required, i.e.\
2161 % in listings that use \mllng{}, and not in others.
2162 % The \hookname{PreInit}, which is called at the very beginning of each
2163 % listing, is where we do that.
2164 % \begin{macro}{\addedToPreInitHook@mlpr}
2165 % In this macro, which we add to \lstpkg{}' \hookname{PreInit} hook, we check
2166 % whether |\lst@language| and |\languageNormedDefd@mlpr| expand (once) to the
2167 % same replacement text and only apply our patches under that condition.
2168 % \begin{macrocode}
2169 \newcommand\addedToPreInitHook@mlpr
2170 {%
2171 \ifx\lst@language\languageNormedDefd@mlpr%
2172 \scaleInlineCode@mlpr%
2173 \renewcommand\addedToInitVarsEOL@mlpr\@ddedToInitVarsEOL@mlpr%
2174 \renewcommand\addedToEndGroup@mlpr\@ddedToEndGroup@mlpr%
2175 \renewcommand\addedToPostOutput@mlpr\@ddedToPostOutput@mlpr%
2176 \renewcommand\addedToOutput@mlpr\@ddedToOutput@mlpr%
2177 \renewcommand\addedToOutputOther@mlpr\@ddedToOutputOther@mlpr%
2178 \DroppingOutput@mlpr@false%
2179 \fi
2180 }
2181 \lst@AddToHook{PreInit}{\addedToPreInitHook@mlpr}
2182 % \end{macrocode}
2183 % \end{macro}
2184 %
2185 % \paragraph{\hookname{DeInit}}
2186 % (See the
2187 % \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}
2188 % for more details on this hook.)
2189 % In the \hookname{DeInit} hook, which is called at the very end of each
2190 % listing, we carry out some housekeeping tasks if the current listing uses
2191 % \mllng{}.
2192 % \begin{macro}{\addedToDeInitHook@mlpr}
2193 % In this macro, which we add to \lstpkg{}' \hookname{DeInit} hook, we check
2194 % whether |\lst@language| and |\languageNormedDefd@mlpr| expand (once) to the
2195 % same replacement text and, under that condition, we reset all state
2196 % variables.
2197 % \begin{macrocode}
2198 \newcommand\addedToDeInitHook@mlpr
2199 {%
2200 \ifx\lst@language\languageNormedDefd@mlpr%
2201 \resetEndKW@mlpr%
2202 \resetClassdefKW@mlpr%
2203 \global\InStr@mlpr@false%
2204 \global\VisCharOccured@mlpr@false%
2205 \global\InSecTitle@mlpr@false%
2206 \global\DroppingOutput@mlpr@false%
2207 \fi
2208 }
2209 \lst@AddToHook{DeInit}{\addedToDeInitHook@mlpr}
2210 % \end{macrocode}
2211 % \end{macro}
2212 %
2213 %
2214 % \section{Key-value interface}
2215 %
2216 % We extend \lstpkg{}' key-value interface by defining several additional
2217 % keys, which we will use to define three \lstpkg{} styles, and which will
2218 % allow the user to customize the style of their \matlab{} listings,
2219 % should they which to do so.
2220 % All \mlpkg{} keys are prefixed by~``|ml|'', so that the user can easily
2221 % distinguish them from ``native'' \lstpkg{} keys.
2222 %
2223 % \paragraph{Keywords}
2224 % \begin{lstkey}{mlkeywordstyle}
2225 % \begin{macro}{\keywordStyle@mlpr}
2226 % In the definition of \mllng{}, we used several classes of \lstpkg{}
2227 % keywords to handle the different \matlab{} keywords;
2228 % here is a style key to ``rule them all''.
2229 % \begin{macrocode}
2230 \newcommand\keywordStyle@mlpr{}
2231 \lst@Key{mlkeywordstyle}\relax%
2232 {\renewcommand\keywordStyle@mlpr{#1}}
2233 % \end{macrocode}
2234 % \end{macro}
2235 % \end{lstkey}
2236 %
2237 % \begin{lstkey}{mllastelementstyle}
2238 % \begin{macro}{\lastElemStyle@mlpr}
2239 % This key determines the style applied to the last-element keyword.
2240 % \begin{macrocode}
2241 \newcommand\lastElemStyle@mlpr{}
2242 \lst@Key{mllastelementstyle}\relax%
2243 {\renewcommand\lastElemStyle@mlpr{#1}}
2244 % \end{macrocode}
2245 % \end{macro}
2246 % \end{lstkey}
2247 %
2248 % \begin{lstkey}{mloverride}
2249 % \begin{macro}{\ifOverridecontext@mlpr@}
2250 % This key overrides the current context, so that context-sensitive
2251 % keywords be typeset in the style associated with the alternative context.
2252 % \begin{macrocode}
2253 \lst@Key{mloverride}{false}[t]%
2254 {\lstKV@SetIf{#1}\ifOverridecontext@mlpr@}
2255 % \end{macrocode}
2256 % \end{macro}
2257 % \end{lstkey}
2258 %
2259 % \paragraph{Strings}
2260 % \begin{lstkey}{mlstringstyle}
2261 % \begin{macro}{\stringStyle@mlpr}
2262 % This key determines the style applied to \matlab{} (quoted and unquoted)
2263 % strings.
2264 % \begin{macrocode}
2265 \newcommand\stringStyle@mlpr{}
2266 \lst@Key{mlstringstyle}\relax%
2267 {\renewcommand\stringStyle@mlpr{#1}}
2268 % \end{macrocode}
2269 % \end{macro}
2270 % \end{lstkey}
2271 %
2272 % \paragraph{Comments}
2273 % \begin{lstkey}{mlcommentstyle}
2274 % \begin{macro}{\commentStyle@mlpr}
2275 % This key determines the style applied to \matlab{}
2276 % (to-end-of-line and block) comments.
2277 % \begin{macrocode}
2278 \newcommand\commentStyle@mlpr{}
2279 \lst@Key{mlcommentstyle}\relax%
2280 {\renewcommand\commentStyle@mlpr{#1}}
2281 % \end{macrocode}
2282 % \end{macro}
2283 % \end{lstkey}
2284 %
2285 % \paragraph{Section titles}
2286 % \begin{lstkey}{mlsectiontitlestyle}
2287 % \begin{macro}{\sectionTitleStyle@mlpr}
2288 % This key determines the style applied to \matlab{} section titles.
2289 % \begin{macrocode}
2290 \newcommand\sectionTitleStyle@mlpr{}
2291 \lst@Key{mlsectiontitlestyle}\relax
2292 {\renewcommand\sectionTitleStyle@mlpr{#1}}
2293 % \end{macrocode}
2294 % \end{macro}
2295 % \end{lstkey}
2296 %
2297 % \begin{lstkey}{mlshowsectionrules}
2298 % \begin{macro}{\ifShowSectRules@mlpr@}
2299 % This key determines whether an horizontal rule gets printed above each
2300 % section title.
2301 % \begin{macrocode}
2302 \lst@Key{mlshowsectionrules}{false}[t]%
2303 {\lstKV@SetIf{#1}\ifShowSectRules@mlpr@}
2304 % \end{macrocode}
2305 % \end{macro}
2306 % \end{lstkey}
2307 %
2308 % \begin{lstkey}{mlsectionrulethickness}
2309 % \begin{macro}{\sectionRuleRT@mlpr}
2310 % This key determines the relative thickness of the horizontal rule that
2311 % gets printed above each section title.
2312 % \begin{macrocode}
2313 \newcommand\sectionRuleRT@mlpr{.05}
2314 \lst@Key{mlsectionrulethickness}\relax%
2315 {\renewcommand\sectionRuleRT@mlpr{#1}}
2316 % \end{macrocode}
2317 % \end{macro}
2318 % \end{lstkey}
2319 %
2320 % \begin{lstkey}{mlsectionrulecolor}
2321 % \begin{macro}{\sectionRuleColor@mlpr}
2322 % This key determines the color of the horizontal rule that gets printed
2323 % above each section title.
2324 % \begin{macrocode}
2325 \newcommand\sectionRuleColor@mlpr{black!15}
2326 \lst@Key{mlsectionrulecolor}\relax%
2327 {\renewcommand\sectionRuleColor@mlpr{#1}}
2328 % \end{macrocode}
2329 % \end{macro}
2330 % \end{lstkey}
2331 %
2332 % \paragraph{System commands}
2333 % \begin{lstkey}{mlsyscomstyle}
2334 % \begin{macro}{\syscomStyle@mlpr}
2335 % This key determines the style applied to system commands.
2336 % \begin{macrocode}
2337 \newcommand\syscomStyle@mlpr{}
2338 \lst@Key{mlsyscomstyle}\relax%
2339 {\renewcommand\syscomStyle@mlpr{#1}}
2340 % \end{macrocode}
2341 % \end{macro}
2342 % \end{lstkey}
2343 %
2344 % \paragraph{Variables with shared scope}
2345 % For convenience, we create a brand new class of \lstpkg{} keywords for
2346 % allowing the user to define \matlab{} variables with shared scope.
2347 %
2348 % \begin{macro}{\InstallKeywords@mlpr}
2349 % This helper macro (which is based on \lstpkg{}' |\lst@InstallKeywords|),
2350 % will let us defines four keys in one go, all prefixed by |ml|.
2351 % \begin{macrocode}
2352 \gdef\InstallKeywords@mlpr#1#2#3#4#5%
2353 {%
2354 \lst@Key{ml#2}\relax
2355 {\lst@UseFamily{#2}[\@ne]##1\relax\lst@MakeKeywords}%
2356 \lst@Key{mlmore#2}\relax
2357 {\lst@UseFamily{#2}[\@ne]##1\relax\lst@MakeMoreKeywords}%
2358 \lst@Key{mldelete#2}\relax
2359 {\lst@UseFamily{#2}[\@ne]##1\relax\lst@DeleteKeywords}%
2360 \ifx\@empty#3\@empty\else
2361 \lst@Key{#3}{#4}{\@namedef{lst@#3}{##1}}%
2362 \fi
2363 \expandafter\lst@InstallFamily@
2364 \csname\@lst @#2@data\expandafter\endcsname
2365 \csname\@lst @#5\endcsname {#1}{#2}{#3}
2366 }
2367 % \end{macrocode}
2368 % \end{macro}
2369 %
2370 % \begin{lstkey}{mlsharedvars}
2371 % \begin{lstkey}{mlmoresharedvars}
2372 % \begin{lstkey}{mldeletesharedvars}
2373 % \begin{lstkey}{mlsharedvarstyle}
2374 % We now use |\InstallKeywords@mlpr| to define the four keys in question:
2375 % \rkeyname{mlsharedvars}, which can be used to define a list of \matlab{}
2376 % variables with shared scope;
2377 % \rkeyname{mlmoresharedvars}, which can be used to add elements to the
2378 % current list of such variables;
2379 % \rkeyname{mldeletesharedvars}, which can be used to remove elements
2380 % from that list;
2381 % and \rkeyname{mlsharedvarstyle}, which determines the style applied to
2382 % variables with shared scope.
2383 % \begin{macrocode}
2384 \InstallKeywords@mlpr k{sharedvars}{mlsharedvarstyle}\relax%
2385 {mlsharedvarstyle}{}ld
2386 % \end{macrocode}
2387 % \end{lstkey}
2388 % \end{lstkey}
2389 % \end{lstkey}
2390 % \end{lstkey}
2391 %
2392 % \paragraph{Delimiters for unquoted strings}
2393 % \begin{lstkey}{mlunquotedstringdelim}
2394 % This key allows the user to define custom delimiters^^A
2395 % ---which do not get printed in the output---^^A
2396 % for unquoted strings.
2397 % \begin{macrocode}
2398 \lst@Key{mlunquotedstringdelim}\relax%
2399 {\lst@DelimKey\relax{[is][\stringStyle@mlpr]{#1}}}
2400 % \end{macrocode}
2401 % \end{lstkey}
2402 %
2403 % \paragraph{Placeholders}
2404 % \begin{lstkey}{mlplaceholderstyle}
2405 % \begin{macro}{\phStyle@mlpr}
2406 % This key determines the style applied to placeholder content;
2407 % the color of placeholder delimiters is designed to match that of
2408 % placeholder content.
2409 % \begin{macrocode}
2410 \newcommand\phStyle@mlpr{}
2411 \lst@Key{mlplaceholderstyle}\relax%
2412 {\renewcommand\phStyle@mlpr{#1}}
2413 % \end{macrocode}
2414 % \end{macro}
2415 % \end{lstkey}
2416 %
2417 % \mlpkg{} currently does not offer a nice interface for customizing
2418 % code-snippet placeholder delimiters; in a future release, perhaps.
2419 %
2420 % \paragraph{Automatic scaling of inline code}
2421 % \begin{lstkey}{mlscaleinline}
2422 % \begin{macro}{\ifScaleInline@mlpr@}
2423 % This key determines whether the font size of inline \matlab{} code should
2424 % match the local font size.
2425 % \begin{macrocode}
2426 \lst@Key{mlscaleinline}{true}[t]%
2427 {\lstKV@SetIf{#1}\ifScaleInline@mlpr@}
2428 % \end{macrocode}
2429 % \end{macro}
2430 % \end{lstkey}
2431 %
2432 % \paragraph{Printing only a function's signature and header}
2433 % \begin{lstkey}{mlonlyheader}
2434 % \begin{macro}{\ifonlyheader@mlpr@}
2435 % This key determines whether output is dropped after the first block of
2436 % contiguous line comments.
2437 % \begin{macrocode}
2438 \lst@Key{mlonlyheader}{false}[t]%
2439 {\lstKV@SetIf{#1}\ifonlyheader@mlpr@}
2440 % \end{macrocode}
2441 % \end{macro}
2442 % \end{lstkey}
2443 %
2444 %
2445 % \section{Two user-level macros}
2446 %
2447 % \begin{macro}{\mlttfamily}
2448 % This user-level macro can be used for selecting a scaled version of the
2449 % Bera Mono font, a typewriter font family which, contrary to typewriter
2450 % \TeX{} fonts, conveniently comes with a boldface version.
2451 % \begin{macrocode}
2452 \newcommand\mlttfamily
2453 {%
2454 \def\fvm@Scale{.85}%
2455 \fontfamily{fvm}\selectfont%
2456 }
2457 % \end{macrocode}
2458 % \end{macro}
2459 %
2460 % \paragraph{Code-snippet placeholders}
2461 % \begin{macro}{\mlplaceholder}
2462 % This user-level macro can be used to typeset placeholders in code snippets.
2463 % \begin{macrocode}
2464 \newcommand\mlplaceholder[1]
2465 {%
2466 \bgroup%
2467 \phStyle@mlpr%
2468 \bgroup%
2469 \phDelimStyle@mlpr%
2470 \phOpDelim@mlpr%
2471 \egroup%
2472 #1\itcorr@mlpr%
2473 \bgroup%
2474 \phDelimStyle@mlpr%
2475 \phClDelim@mlpr%
2476 \egroup%
2477 \egroup%
2478 }
2479 % \end{macrocode}
2480 % \end{macro}
2481 %
2482 %
2483 % \section{Other helper macros}
2484 %
2485 % \begin{macrocode}
2486 \newcommand\phDelimStyle@mlpr{\rmfamily\upshape}
2487 % \end{macrocode}
2488 % \begin{macrocode}
2489 \newcommand\phOpDelim@mlpr{\textlangle}
2490 % \end{macrocode}
2491 % \begin{macrocode}
2492 \newcommand\phClDelim@mlpr{\textrangle}
2493 % \end{macrocode}
2494 %
2495 % \begin{macro}{\itcorr@mlpr}
2496 % This macro is used for applying italic correction in case the current font
2497 % shape is either italic or slanted.
2498 % \begin{macrocode}
2499 \newcommand\itcorr@mlpr
2500 {%
2501 % \end{macrocode}
2502 % We define a (long) macro that expands (once) to the current font shape,
2503 % for comparison purposes.
2504 % \begin{macrocode}
2505 \expandafter\newcommand\expandafter\long@f@shape@mlpr%
2506 \expandafter{\f@shape}%
2507 % \end{macrocode}
2508 % If the current font shape is either italic or slanted, we apply italic
2509 % correction.
2510 % \begin{macrocode}
2511 \ifx\long@f@shape@mlpr\itdefault%
2512 \/%
2513 \else
2514 \ifx\long@f@shape@mlpr\sldefault%
2515 \/%
2516 \fi
2517 \fi
2518 }
2519 % \end{macrocode}
2520 % \end{macro}
2521 %
2522 %
2523 % \section{\texorpdfstring{\mlpkg{}}{matlab-prettifier} styles}
2524 %
2525 % We now define three \lstpkg{} styles for \matlab{} listings.
2526 %
2527 % \paragraph{Base style}
2528 %
2529 % This style is used internally to define the three user-level styles.
2530 % It's not meant to be used outside this package file.
2531 % \begin{macro}{\toks@mlpr}
2532 % We allocate a token list register in which we store settings that we'll use
2533 % to define the style.
2534 % \begin{macrocode}
2535 \newtoks\toks@mlpr
2536 \toks@mlpr=%
2537 {
2538 language = \languageNormedDefd@mlpr,
2539 basicstyle = \color{black}\ttfamily\normalsize,
2540 breaklines = true,
2541 showspaces = false,
2542 showstringspaces = false,
2543 upquote = true,
2544 rulecolor = \color{black!67},
2545 numberstyle = \color{black!33},
2546 mlscaleinline = true,
2547 mlonlyheader = false,
2548 }
2549 % \end{macrocode}
2550 % \end{macro}
2551 % \begin{macrocode}
2552 \ifframed@mlpr@
2553 \toks@mlpr=\expandafter{\the\toks@mlpr frame=single,}
2554 \fi
2555 \ifnumbered@mlpr@
2556 \toks@mlpr=\expandafter{\the\toks@mlpr numbers=left,}
2557 \fi
2558 \begingroup\edef\@tempa{\endgroup
2559 \noexpand\lstdefinestyle{MatlabBaseStyle@mlpr}{\the\toks@mlpr}
2560 }\@tempa
2561 % \end{macrocode}
2562 %
2563 % \paragraph{Standard style}
2564 % Standard style of the \matlab{} editor.
2565 % \begin{macro}{\mlbwphstyle}^^A FIXME: to be documented
2566 % This user macro holds the placeholder style used in the
2567 % \mlsty{Matlab-editor} style.
2568 % \begin{macrocode}
2569 \newcommand\mleditorphstyle{\color[RGB]{209,000,086}\rmfamily\itshape}
2570 % \end{macrocode}
2571 % \end{macro}
2572 % \begin{macrocode}
2573 \lstdefinestyle{Matlab-editor}
2574 {
2575 style = MatlabBaseStyle@mlpr,
2576 mllastelementstyle = \color{black} ,
2577 mlkeywordstyle = \color[RGB]{000,000,255} ,
2578 mlcommentstyle = \color[RGB]{034,139,034} ,
2579 mlstringstyle = \color[RGB]{160,032,240} ,
2580 mlsyscomstyle = \color[RGB]{178,140,000} ,
2581 mlsectiontitlestyle = \commentStyle@mlpr \bfseries,
2582 mlsharedvarstyle = \color[RGB]{000,163,163} ,
2583 mlplaceholderstyle = \mleditorphstyle,
2584 }
2585 % \end{macrocode}
2586 %
2587 % \paragraph{Black \& white style}
2588 % Black \& white, printer-friendly style.
2589 % \begin{macro}{\mlbwphstyle}^^A FIXME: to be documented
2590 % This user macro holds the placeholder style used in the
2591 % \mlsty{Matlab-bw} style.
2592 % \begin{macrocode}
2593 \newcommand\mlbwphstyle{\color[gray]{0}\rmfamily\itshape}
2594 % \end{macrocode}
2595 % \end{macro}
2596 % \begin{macrocode}
2597 \lstdefinestyle{Matlab-bw}
2598 {
2599 style = MatlabBaseStyle@mlpr,
2600 mlkeywordstyle = \color[gray]{0} \bfseries ,
2601 mlcommentstyle = \color[gray]{.75} \itshape,
2602 mlstringstyle = \color[gray]{.5} ,
2603 mlsyscomstyle = \color[gray]{.25} ,
2604 mlsectiontitlestyle = \color[gray]{.75}\bfseries\itshape,
2605 mlsharedvarstyle = \color[gray]{0} ,
2606 mlplaceholderstyle = \mlbwphstyle,
2607 }
2608 % \end{macrocode}
2609 %
2610 % \paragraph{Style of Pygments' MatlabLexer}
2611 % Style that closely mimics that of Pygments' `MatlabLexer'.
2612 % \begin{macro}{\mlpyglikephstyle}^^A FIXME: to be documented
2613 % This user macro holds the placeholder style used in the
2614 % \mlsty{Matlab-Pyglike} style.
2615 % \begin{macrocode}
2616 \newcommand\mlpyglikephstyle{\color[RGB]{127,063,127}\rmfamily\itshape}
2617 % \end{macrocode}
2618 % \end{macro}
2619 % \begin{macrocode}
2620 \lstdefinestyle{Matlab-Pyglike}
2621 {
2622 style = MatlabBaseStyle@mlpr,
2623 mllastelementstyle = \color[RGB]{127,000,000} ,
2624 mlkeywordstyle = \color[RGB]{000,127,000}\bfseries ,
2625 mlcommentstyle = \color[RGB]{063,127,127} \itshape,
2626 mlstringstyle = \color[RGB]{186,034,034} ,
2627 mlsyscomstyle = \color[RGB]{000,127,000} ,
2628 mlsectiontitlestyle = \color[RGB]{063,127,127} \itshape,
2629 mlsharedvarstyle = \color[RGB]{034,034,186} ,
2630 mlplaceholderstyle = \mlpyglikephstyle,
2631 }
2632 % \end{macrocode}
2633 %
2634 % \Finale
2635 \endinput