matlab-prettifier (19jun14)

git-svn-id: svn://tug.org/texlive/trunk@34323 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 2701 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/matlab-prettifier/matlab-prettifier.dtx b/Master/texmf-dist/source/latex/matlab-prettifier/matlab-prettifier.dtx
new file mode 100644
index 00000000000..cb8145299b4
--- /dev/null
+++ b/Master/texmf-dist/source/latex/matlab-prettifier/matlab-prettifier.dtx
@@ -0,0 +1,2635 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2014 by Julien Cretel
+%                       <jubobs.matlab.prettifier at gmail.com>
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+%
+%     http://www.latex-project.org/lppl.txt
+%
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% \fi
+%
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[2011/06/27]
+%<package>\ProvidesPackage{matlab-prettifier}
+%<package>  [2014/06/19 v0.3 A package for prettyprinting Matlab source code]
+%
+%<*driver>
+\documentclass[a4paper]{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage{xcolor}
+\usepackage{lstdoc}
+\usepackage[framed,numbered]{matlab-prettifier}
+\usepackage{hyperref}
+\usepackage{cleveref}
+
+\lstset
+{
+  style                 = Matlab-editor,
+  basicstyle            = \normalsize\mlttfamily,
+  upquote               = true,
+  mlunquotedstringdelim = {/*}{*/},
+  mlmoresharedvars      = {myglobalvar},
+}
+\lstdefinestyle{nonbnoframe}
+{
+  frame   = none,
+  numbers = none,
+}
+\lstMakeShortInline"
+\newcommand\ph\mlplaceholder
+\newcommand*{\pkg}[1]{\textsf{#1}}
+\newcommand*{\opt}[1]{\texttt{#1}}
+\newcommand\lstpkg{\pkg{listings}}
+\newcommand*{\lststy}[1]{\texttt{#1}}
+\newcommand*{\lstlng}[1]{\texttt{#1}}
+\newcommand\matlab{\textsc{Matlab}}
+\newcommand\octave{\textsc{Octave}}
+\newcommand\matlabver{\matlab~(R2013a)}
+\newcommand\mathworks{MathWorks}
+\newcommand*\trademark[1]{#1\textsuperscript{\textregistered}}
+\newcommand\mlpkg{\pkg{matlab-prettifier}}
+\newcommand\mllng{\texttt{Matlab-pretty}}
+\newcommand*{\mlsty}[1]{\texttt{#1}}
+\newcommand\overrideEnd{\lstinline[mloverride]|end|}
+\newcommand\overrideEnumeration{\lstinline[mloverride]|enumeration|}
+\newcommand\overrideMethods{\lstinline[mloverride]|methods|}
+\newcommand\overrideProperties{\lstinline[mloverride]|properties|}
+\newcommand\overrideEvents{\lstinline[mloverride]|events|}
+\newcommand\itemp{\item[\(+\)]}
+\newcommand\itemm{\item[\(-\)]}
+
+\makeindex
+
+\begin{document}
+  \DocInput{matlab-prettifier.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{671}
+%
+% \CharacterTable
+%  {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
+%   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
+%   Digits        \0\1\2\3\4\5\6\7\8\9
+%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%   Dollar        \$     Percent       \%     Ampersand     \&
+%   Acute accent  \'     Left paren    \(     Right paren   \)
+%   Asterisk      \*     Plus          \+     Comma         \,
+%   Minus         \-     Point         \.     Solidus       \/
+%   Colon         \:     Semicolon     \;     Less than     \<
+%   Equals        \=     Greater than  \>     Question mark \?
+%   Commercial at \@     Left bracket  \[     Backslash     \\
+%   Right bracket \]     Circumflex    \^     Underscore    \_
+%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%   Right brace   \}     Tilde         \~}
+%
+% \changes{v0.1}{2014/04/24}{Initial release.}
+% \changes{v0.2}{2014/04/25}{
+%   Refactor code extensively;
+%   rewrite automatic scaling of inline code;
+%   implement mlscaleinline key;
+%   implement mlonlyheader.
+% }
+% \changes{v0.3}{2014/06/19}{
+%   Change default font from Bera Mono to Computer Modern typewriter
+%   (for compatibility reasons);
+%   fix bug (end keyword now gets reset by a semicolon);
+%   rename placeholder user macro; 
+%   mention support for a subset of Octave's syntax.
+% }
+%
+% \GetFileInfo{matlab-prettifier.sty}
+%
+%  ^^A see http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex%2F3540
+%  \begingroup
+%    \def\x{\#,\$,\%,\^,\_,\~,\&,\{,\},\/}%^^A
+%    \makeatletter
+%    \@onelevel@sanitize\x
+%  \expandafter\endgroup\expandafter\DoNotIndex\expandafter{\x}
+%
+% \begingroup
+%    \makeatletter
+%    \lccode`9=32\relax
+%    \lowercase{%^^A
+%      \edef\x{\noexpand\DoNotIndex{\@backslashchar9}}%^^A
+%    }%^^A
+%  \expandafter\endgroup\x
+%
+% \DoNotIndex{\@empty,\@ifpackagewith,\@lst,\@namedef,\@ne,\@tempa}
+% \DoNotIndex{\advance}
+% \DoNotIndex{\baselineskip,\begingroup,\bfseries,\bgroup}
+% \DoNotIndex{\ClosingEndKW@mlpr@false,\ClosingEndKW@mlpr@true,^^A
+%   \color,\colorlet,\csname,\CurrentOption}
+% \DoNotIndex{\DeclareOption,\def,\definecolor,\dimexpr,^^A
+%   \DroppingOutput@mlpr@false,\DroppingOutput@mlpr@true}
+% \DoNotIndex{\edef,\egroup,\else,\endcsname,\endgroup,\expandafter}
+% \DoNotIndex{\f@baselineskip,\f@shape,\f@size,\fi,\font,\fontsize,^^A
+%   \fontchardp,\fontcharht,\fontfamily,\framed@mlpr@true,\fvm@Scale}
+% \DoNotIndex{\gdef,\global}
+% \DoNotIndex{\ifnum,\ifx,^^A
+%   \InClassdef@mlpr@false,\InClassdef@mlpr@true,^^A
+%   \InSecTitle@mlpr@false,\InSecTitle@mlpr@true,^^A
+%   \InStr@mlpr@false,\InStr@mlpr@true,^^A
+%   \itdefault,\itshape}
+% \DoNotIndex{\let,\lst@basicstyle,\lst@BeginDropOutput,\lst@AddToHook,^^A
+%   \lst@CalcLostSpaceAndOutput,\lst@DefSaveDef,\lst@DelimKey,^^A
+%   \lst@EnterMode,\lst@ifdisplaystyle,\lst@ifLmode,\lst@ifwhitespace,^^A
+%   \lst@InstallKeywords,\lst@Key,\lst@language,\lst@LeaveMode,^^A
+%   \lst@lineno,\lst@linewidth,\lst@Lmodetrue,\lst@mode,\lst@modetrue,^^A
+%   \lst@NormedDef,\lst@Pmode,\lst@DeleteKeywords,\lst@InstallFamily@,^^A
+%   \lst@MakeKeywords,\lst@MakeMoreKeywords,\lst@UseFamily,^^A
+%   \lstdefinelanguage,\lstdefinestyle,\lstKV@SetIf}
+% \DoNotIndex{\m@ne,\makebox}
+% \DoNotIndex{\newcommand,\newcount,\newif,\newlength,\newtoks,\normalsize,^^A
+%   \numbered@mlpr@true,\noexpand}
+% \DoNotIndex{\OptionNotUsed}
+% \DoNotIndex{\PackageError,\PackageWarning,\ProcessOptions}
+% \DoNotIndex{\raisebox,\relax,\renewcommand,\RequirePackage,\rule,\rmfamily}
+% \DoNotIndex{\selectfont,\setlength,\sldefault,\textlangle,\textrangle,^^A
+%   \ttfamily}
+% \DoNotIndex{\the}
+% \DoNotIndex{\upshape}
+% \DoNotIndex{\VisCharOccured@mlpr@true,\VisCharOccured@mlpr@false}
+%
+% \title^^A
+% {^^A
+%   The \mlpkg{} package^^A
+%   \thanks^^A
+%   {^^A
+%     This document corresponds to \mlpkg~\fileversion,
+%     dated~\filedate.^^A
+%   }^^A
+%  }
+% \author{Julien Cretel\\ \texttt{jubobs.matlab.prettifier at gmail.com}}
+% \date{\filedate}
+% \thispagestyle{empty}
+% \maketitle
+%
+% \begin{abstract}
+%   Built on top of the \lstpkg{} package, the \mlpkg{} package allows you to
+%   effortlessly prettyprint \matlab{} source code in documents typeset with
+%   \LaTeX{} \& friends. Three predefined styles, one of which closely mimics
+%   that of the \matlab{} editor, are available and can be invoked by
+%   \lstpkg{} macros and environments in conjunction with (most) options
+%   provided by the \lstpkg{} package. The appearance of your \matlab{}
+%   listings can be further tweaked via a key-value interface extending that
+%   of \lstpkg{}'. Partial support for Octave syntax is provided.
+% \end{abstract}
+%
+% \tableofcontents\newpage
+%
+%
+% \part{Introduction}
+%
+% \section{Why this package?}
+%
+% \trademark{\matlab} is a high-level language and interactive environment for
+% numerical computation, visualization, and programming.^^A
+%   \footnote{Source: \url{http://www.mathworks.co.uk/products/matlab/}}
+% Despite being proprietary and occasionally frustrating, \matlab{} remains a
+% great tool for prototyping matrix-oriented, number-crunching programs.
+% As such, it enjoys widespread popularity, especially in academia,
+% where, in particular, it is often used for teaching numerical methods.
+%
+% Users of both \matlab{} and \LaTeX{} (and friends) often need to typeset
+% \matlab{} listings in \LaTeX{} documents, usually with some syntax
+% highlighting, for improved code readability;
+% the relatively large number of relevant questions posted on
+% \href{http://tex.stackexchange.com/search?q=matlab+code+is%3Aquestion}^^A
+% {tex.stackexchange.com} attests to that need.
+%
+% Recent versions of \matlab{} provide a built-in function, called "publish",
+%  that can generate \LaTeX{} code for typesetting \matlab{} listings, but
+% that function uses a |verbatim| environment, which doesn't allow for any
+% fancy formatting.
+% Several \LaTeX{} packages^^A
+% ---vanilla \lstpkg{}, \pkg{mcode}, and \pkg{minted}, among others---^^A
+% allow for automatic syntax highlighting of \matlab{} listings in \LaTeX{}
+% documents.
+% However, none of those packages do a great job at replicating the very
+% specific syntax-highlighting style performed on the fly by the \matlab{}
+% editor.^^A
+%   \footnote{see ... for a comparison.}
+%  
+% The lack of tools for faithfully mimicking the style of the \matlab{}
+% editor is unfortunate, especially from an educational standpoint, for the
+% following reason.
+% Most newcomers to \matlab{} read and write code in the \matlab{} editor
+% and are, therefore, continually exposed to its highlighting style.
+% Visual cues^^A
+% ---such as those provided by syntax highlighting---^^A
+% play an important role for recognising patterns,
+% and students of a programming language are more likely to quickly and
+% effectively learn and recognize its syntax if they see it highlighted in a
+% consistent manner, whether it be in a text editor or in some course material
+% (lab handout, assignment paper, etc.).
+%
+% The \mlpkg{} package is intended to fill that gap.
+% Built on top of the feature-rich \lstpkg{} package, \mlpkg{} allows you to
+% beautifully and effortlessly typeset \matlab{} listings, as it configures
+% \lstpkg{} ``behind the scenes'' to replicate, as closely as possible, the
+% syntax-highlighting style of the \matlab{} editor.
+%
+% What about code written in \octave{} (a free alternative to \matlab{})?
+% Because \octave{}'s syntax and \matlab{}'s syntax
+% \href{http://wiki.octave.org/FAQ#How_is_Octave_different_from_Matlab.3F}
+%   {overlap a lot},
+% \mlpkg{} correctly highlights \octave{} listings that strictly adhere to
+% the subset of syntax that lies in this overlap.
+% More support for \octave{} is expected to ship with a future release.
+%
+% Furthermore, \mlpkg{} comes with a few additional features that should make
+% your life easier. Read on!
+%
+%
+% \section{Review of alternatives to \mlpkg{}}
+%
+% Here is a review of the different alternatives^^A
+% ---other than the \mlpkg{} package and \matlab{}'s "publish" function---^^A
+% available for typesetting \matlab{} listings in \LaTeX{} documents.
+%
+% \paragraph{\lstpkg{}' \lstlng{Matlab} language} 
+%^^A
+% \begin{itemize}
+%   \itemp A starting point!
+%   \itemp \lstpkg{}' rich features are available.
+%   \itemp Settings for \matlab{} listings are bundled into a \lstpkg{}
+%     language, which can be invoked \emph{locally}.
+%   \itemm Some \matlab{} keywords (e.g.\ "parfor") are not listed.
+%   \itemm Built-in \matlab{} function names (e.g.\ "sum") get highlighted
+%     like \matlab{} keywords do, which is very distracting.
+%   \itemm Highlighting of keywords is not context-aware;
+%     in particular, the |end| keyword gets typeset in the same style,
+%     regardless of the context (closing keyword or last-element keyword)
+%     in which it occurs.
+%   \itemm No highlighting of block comments
+%   \itemm No highlighting of line-continuation token and associated comment
+%   \itemm Section titles are not highlighted in a style distinct from that of
+%     comments.
+%   \itemm No highlighting of unquoted strings
+% \end{itemize}
+%
+% \paragraph{\pkg{mcode}}
+%^^A
+% \begin{itemize}
+%   \itemp An honest attempt at improving \lstpkg{}' \lstlng{Matlab} language
+%   \itemp Package options for quickly effecting global changes to the look
+%     of \matlab{} listings
+%   \itemp Block comments are highlighted as such.
+%   \itemp A line-continuation token activates comment style\ldots
+%   \itemm \ldots but also gets highlighted in comment style.
+%   \itemm Settings for \matlab{} listings are defined \emph{globally}
+%     (using |\lstset|) rather than locally,
+%     which means those settings can easily be overwritten/lost.
+%   \itemm The \overrideEnumeration{} keyword is not listed.
+%   \itemm Highlighting of the last-element keyword is handled by a series of
+%     literate replacements;
+%     this approach works well only in a limited number of cases in which
+%     that keyword occurs.
+%   \itemm Highlighting of the four context-sensitive class-definition
+%     keywords is not context-aware;
+%     in particular, |properties| gets typeset in the same style,
+%     regardless of the context (function or class-definition keyword)
+%     in which it occurs.
+%   \itemm Undesirable literate replacements
+%     ("<=" by~\(\leq\), "delta" by~\(\Delta\)) are forced upon the users,
+%     and cannot be easily prevented without breaking other literate
+%     replacements put in place for highlighting the last-element keyword.
+%   \itemm Section titles are not highlighted in a style distinct from that of
+%     comments.
+%   \itemm No highlighting of unquoted strings
+%   \itemm The implementation of \pkg{mcode} lacks ``namespacing'',
+%     which increases the risk of conflict with other packages.
+%   \itemm \pkg{mcode} is currently not available on
+%     \href{http://ftp.heanet.ie/pub/CTAN/tex/support/ctanify/ctanify.pdf}
+%       {CTAN}.
+% \end{itemize}
+%
+% \paragraph{Pygments-based packages
+%   (\pkg{minted}, \pkg{verbments}, \pkg{pythontex})}
+%^^A
+% \begin{itemize}
+%   \itemp Python!
+%   \itemp Pygments!
+%   \itemp Slick look
+%   \itemp Block comments are highlighted as such.
+%   \itemp A line-continuation token activates comment style\ldots
+%   \itemm \ldots but also gets highlighted in comment style.
+%   \itemm \lstpkg{}' features are not available.
+%   \itemm Highlighting of keywords is not context-aware;
+%     in particular, the last-element keyword gets highlighted like the
+%     closing keyword does, which is very distracting.
+%   \itemm \matlab{}'s transpose operator (".'") and "}'" are incorrectly
+%     interpreted as starting a string literal.
+%   \itemm No highlighting of unquoted strings
+%   \itemm Escape to \LaTeX{} is only allowed in comments.
+%   \itemm Slow compared to \lstpkg{}
+%   \itemm Requires |-shell-escape|
+% \end{itemize}
+%
+%
+% \section{Syntactic elements automatically highlighted by \mlpkg{}}
+% 
+% The \mlpkg{} package defines a \pkg{listings} language called
+% \mllng{}, which is designed to keep track of the context behind the scenes
+% and, therefore, facilitates context-sensitive highlighting of various
+% elements of \matlab{} syntax.
+% That language is used as a basis for three \lstpkg{} styles,
+% one of which, called \mlsty{Matlab-editor}, is showcased below.
+% 
+% \paragraph{Context-insensitive keywords}
+% "while", "for", "break", etc.
+%
+% \paragraph{Context-sensitive keywords}
+% "end",
+% \overrideEvents{},
+% \overrideProperties{},
+% etc.
+% 
+% \paragraph{Quoted strings}
+% \mbox{}
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[numbers=none]
+'The sleeper must awaken.'
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{To-end-of-line and block comments}
+% \mbox{}
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[numbers=none]
+% Now let's assign the value of pi to variable a
+a = pi
+%{
+ Now that a holds the value of pi,
+ here is what we're going to do...
+ blah blah blah
+%}
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+% 
+% \paragraph{Line-continuation token (and associated to-end-of-line comment)}
+% \mbox{}
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[numbers=none]
+A = [ 1, 2, 3,... (second row defined on next line)
+      4, 5, 6];
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Section titles}
+% \mbox{}
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[numbers=none]
+%% Variable initialization
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{System commands}
+% \mbox{}
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[numbers=none]
+! gzip sample.m
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+%
+%
+% \section{Styles provided by \mlpkg{}}
+%
+% The package defines three \lstpkg{} \emph{styles} for \matlab{} code:
+% \mlsty{Matlab-editor}, \mlsty{Matlab-bw}, and
+% \mlsty{Matlab-Pyglike}.
+% Those styles differ in terms of color scheme but, for convenience,
+% all three activate automatic line breaking;
+% for more defails about automatic line breaking, see subsection~4.10 in
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
+% 
+% Here is a comparison of the three styles defined by \mlpkg{}.
+%
+% \paragraph{\mlsty{Matlab-editor}}
+% This style mimics the default style of the \matlab{} editor.
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[style=Matlab-editor,basicstyle=\mlttfamily]
+%% Sample Matlab code
+!mv test.txt test2.txt
+A = [1, 2, 3;... foo
+     4, 5, 6];
+s = 'abcd';
+for k = 1:4
+  disp(s(k)) % bar
+end
+%{
+create row vector x, then reverse it
+%}
+x = linspace(0,1,101);
+y = x(end:-1:1);
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{\mlsty{Matlab-bw}}
+% This style is mainly for black \& white printing.
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[style=Matlab-bw,basicstyle=\mlttfamily]
+%% Sample Matlab code
+!mv test.txt test2.txt
+A = [1, 2, 3;... foo
+     4, 5, 6];
+s = 'abcd';
+for k = 1:4
+  disp(s(k)) % bar
+end
+%{
+create row vector x, then reverse it
+%}
+x = linspace(0,1,101);
+y = x(end:-1:1);
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{\mlsty{Matlab-Pyglike}}
+% The \pkg{minted}, \pkg{verbments}, and \pkg{pythontex} packages all use
+% \href{http://pygments.org}{Pygments} lexers for syntax highlighting of
+% listings.
+% This \mlpkg{} style closely mimics the default style associated with
+% Pygments' `MatlabLexer'.
+% \iffalse
+%<*example>
+% \fi
+\begin{lstlisting}[style=Matlab-Pyglike,basicstyle=\mlttfamily]
+%% Sample Matlab code
+!mv test.txt test2.txt
+A = [1, 2, 3;... foo
+     4, 5, 6];
+s = 'abcd';
+for k = 1:4
+  disp(s(k)) % bar
+end
+%{
+create row vector x, then reverse it
+%}
+x = linspace(0,1,101);
+y = x(end:-1:1);
+\end{lstlisting}
+% \iffalse
+%</example>
+% \fi
+%
+%
+% \section{Other features}
+%
+% Additional features include
+%
+% \begin{itemize}
+%   \item a key-value interface extending that of the \lstpkg{} package,
+%   \item manual highlighting of variables with shared scope
+%     (e.g.\ "myglobalvar"),
+%   \item manual highlighting of unquoted strings
+%     (e.g.\ ``on'' in ``"hold /*on*/"''),
+%   \item a macro for easily typesetting placeholders
+%     (e.g.\ \ph{initial-value}),
+%   \item automatic scaling of inline code according to its surroundings,
+%   \item an option to only print the header of a \matlab{} function.
+% \end{itemize}
+% 
+%
+% \part{User's guide}
+%
+% \section{Installation}
+%
+% \subsection{Package dependencies}
+%
+% \mlpkg{} requires relatively up-to-date versions of packages \pkg{textcomp},
+% \pkg{xcolor}, and \lstpkg{}, all three of which ship with popular \TeX{}
+% distributions. It loads those three packages without any options.
+%
+%
+% \subsection{Installing \mlpkg{}}
+%
+% Since the package has been officially released on
+% \href{http://www.ctan.org/pkg/matlab-prettifier}{CTAN},
+% you should be able to install it directly through your package manager.
+%
+% However, if you need to install \mlpkg{} manually, you should run
+%^^A
+% \begin{verbatim}
+%   latex matlab-prettifier.ins\end{verbatim}
+%^^A
+% and copy the file called |matlab-prettifier.sty| to a path
+% where \LaTeX{} (or your preferred typesetting engine) can find it.
+% To generate the documentation, run
+%^^A
+% \begin{verbatim}
+%   pdflatex matlab-prettifier.dtx
+%   makeindex -s gglo.ist -o matlab-prettifier.gls matlab-prettifier.glo
+%   makeindex -s gind.ist -o matlab-prettifier.ind matlab-prettifier.idx
+%   pdflatex matlab-prettifier.dtx
+%   pdflatex matlab-prettifier.dtx\end{verbatim}
+%^^A
+%
+%
+% \section{Getting started}
+%
+% As stated above, the \mlpkg{} package is built on top of the \lstpkg{}
+% package.
+% If you already are a seasoned \lstpkg{} user, you should feel right at home.
+% If you're not, be aware that this user's guide makes use of some \lstpkg{}
+% functionalities (such as key-value options) without describing their usage.
+% For more details on those functionalities, you should consult the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
+%
+%
+% \subsection{Loading \texorpdfstring{\mlpkg{}}{matlab-prettifier}}
+%
+% Simply write
+%^^A
+% \begin{verbatim}
+%   \usepackage{matlab-prettifier}\end{verbatim}
+%^^A
+% somewhere in your preamble.
+%
+% You may want to load the \lstpkg{} and
+% \pkg{xcolor} packages with some options; in that case, make sure those
+% options are passed to those two packages \emph{before} loading the \mlpkg{}
+% package.
+%
+% The \mlpkg{} package currently offers four options.
+% The first two are inspired from the \pkg{mcode} package.
+% The last two are simply \lstpkg{} options that \mlpkg{} passes to \lstpkg{}
+% behind the scenes;
+% I chose to define those two options as \mlpkg{} options to save you
+% the hassle of loading them with \lstpkg{} separately,
+% should you wish to use them.
+%^^A
+% \begin{description}
+% \item[\opt{framed}]\leavevmode
+%
+%       Draws (by default) a dark gray frame around each listing that uses
+%       one of the three styles defined by \mlpkg{}.
+%
+% \item[\opt{numbered}]\leavevmode
+%
+%       Prints (by default) line numbers in light gray to the left of each
+%       listing that uses one of the three styles defined by \mlpkg{}.
+%
+% \item[\opt{draft}]\leavevmode
+%
+%       This is simply \lstpkg{}' \opt{draft} option.
+%       For more details, see subsection~2.2 of the
+%       \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
+%
+% \item[\opt{final}]\leavevmode
+%
+%       This is simply \lstpkg{}' \opt{final} option.
+%       For more details, see subsection~2.2 of the
+%       \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}.
+% \end{description}
+%
+%
+% \subsection{Displayed listings}
+%
+% To typeset a \matlab{} listing embedded in your |tex| file, simply enclose
+% it in an |lstlisting| environment, and load some style in the environment's
+% optional argument, using \lstpkg{}' \keyname{style} key.
+%^^A
+% \begin{verbatim}
+%   \begin{lstlisting}[style=Matlab-editor]
+%     ...
+%   \end{lstlisting}\end{verbatim}
+%
+%
+% \subsection{Standalone listings}
+%
+% In practice, though, keeping your \matlab{} listings in external files^^A
+% ---rather than embedding them in a |tex|~file---^^A
+% is preferable, for maintainability reasons.
+% To typeset a \matlab{} listing residing in an m-file, simply invoke the
+% |\lstinputlisting| macro; load some style in the environment's
+% optional argument, and specify the path to the m-file in question in the
+% mandatory argument.
+%^^A
+% \begin{verbatim}
+%   \lstinputlisting[style=Matlab-editor]{sample.m}\end{verbatim}
+%^^A
+%
+%
+% \subsection{Inline listings}
+%
+% You may want to typeset fragments of \matlab{} code within the main text of
+% your document. For instance, you may want to typeset the "break" keyword in
+% a sentence, in order to explain its usage.
+% The |\lstinline| macro can be used for typesetting such inline code.
+%^^A
+% \begin{verbatim}
+%   \lstinline[style=Matlab-style]!break!\end{verbatim}
+%^^A
+% Well, that's quite a mouthful for such a simple \matlab{} keyword!
+% Writing |\lstinline| for each instance of inline \matlab{} code in your
+% document can rapidly become tedious.
+% Fortunately, \lstpkg{} allows its users to define a character as a shorthand
+% for inline code via the |\lstMakeShortInline| macro.
+% For instance, you could define the double-quote character~(|"|) as a
+% shorthand for inline \matlab{} code with
+%^^A
+% \begin{verbatim}
+%   \lstMakeShortInline[style=Matlab-editor]"\end{verbatim}
+%^^A
+% and you would then be able to typeset this "break" keyword simply by writing
+%^^A
+% \begin{verbatim}
+%   "break"\end{verbatim}
+%^^A
+% in your |tex| file (but outside displayed listings, of course).
+% 
+% You should choose a character that does not otherwise occur in your
+% |tex| file, especially in the inline \matlab{} code itself,
+% or you run the risk of confusing \TeX{}.
+% I find that, in general, the double-quote character~(|"|) offers a good
+% compromise.
+% If necessary, you can undefine a character as a shorthand for inline code,
+% via \lstpkg{}' |\lstDeleteShortInline| macro.
+% For more details, see subsection~4.17 in the \lstpkg{} manual.
+%
+%
+% \subsection{Placeholders}
+%
+% Code-snippet placeholders, such as \ph{initial-value}, are particularly
+% useful for educational purposes, e.g.\ to describe the syntax of a
+% programming language to students.
+% The following macro allows you to typeset such placeholders, both
+% inside and outside listings:
+%^^A
+% \begin{syntax}
+%
+%   \item[0.1] \rcmdname\mlplaceholder|{|\meta{placeholder content}|}|
+%
+%     typesets a code-snippet placeholder.
+%     You can use this macro both inside and outside listings.
+%     When used inside listings, it must be invoked within an
+%     \emph{escape to \LaTeX{}}; see subsection~4.14 of the \lstpkg{} manual.
+%
+% \end{syntax}
+%
+% If you choose to define a single character for escaping to \LaTeX{} (via
+% \lstpkg{}' \keyname{escapechar} key), I recommend you define
+% either the double-quote character~(|"|)
+% or the backtick character~(\texttt{\`{}})
+% as escape character,
+% because neither is allowed in \matlab{} statements and expressions^^A
+% ---although they may occur in \matlab{} string literals.
+% Note that using~|"| both as shorthand for inline code and as an
+% escape-to-\LaTeX{} character inside listings is perfectly allowed.
+% 
+% The following example illustrates how placeholders may be used to describe
+% the syntax of the \matlab{} while loop.
+%^^A
+% \begin{lstsample}{}{\lstset{style=nonbnoframe}}
+%    \begin{lstlisting}[
+%      style=Matlab-editor,
+%      basicstyle=\mlttfamily,
+%      escapechar=`,
+%    ]
+%    while `\mlplaceholder{condition}`
+%      if `\mlplaceholder{something-bad-happens}`
+%        break
+%      else
+%        % do something useful
+%      end
+%    end
+%    \end{lstlisting}
+% \end{lstsample}
+%
+% For convenience, you can of course define a custom macro with a shorter
+% name for typesetting placeholders, e.g.~|\ph|:
+%^^A
+% \begin{verbatim}
+%   \newcommand\ph\mlplaceholder\end{verbatim}
+%
+%
+% \section{Advanced customization}
+%
+% The \lstpkg{} package provides a large number of options accessible via a
+% nifty key-value interface, which is described in its excellent
+% \href{http://www.ctan.org/pkg/listings}{documentation}.
+% The \mlpkg{} package extends \lstpkg{}' key-value interface interface by
+% defining several additional keys that allow you to customize the style of
+% your \matlab{} listings, should you wish to do so.
+% All the keys provided by \mlpkg{} are prefixed by ``|ml|'',
+% to help you distinguish them from native \lstpkg{} keys.
+% 
+%
+% \subsection{Keys from the \lstpkg{} that you should not use}
+%
+% The great majority of keys provided by \lstpkg{} can be used in conjunction
+% with keys provided by \mlpkg{} without any detrimental side effects,
+% but there are a few exceptions that you should keep in mind.
+% 
+% Some \mlpkg{} keys rely on \lstpkg{} keys ``under the hood'',
+% and using those \mlpkg{} and \lstpkg{} keys in conjunction is
+% \emph{strongly discouraged},
+% because doing so has the potential to wreak havok on the syntax highlighting
+% of \matlab{} listings.
+% It would be like \emph{crossing the streams}: it would be \emph{bad}!
+%
+% For instance, if you want to change the way \matlab{} keywords are typeset,
+% you should use the dedicated \mlpkg{} key called \rkeyname{mlkeywordstyle}
+% and eschew the \lstpkg{} key called \keyname{keywordstyle}.
+% More generally, if \lstpkg{} provides a key called \meta{something} and
+% \mlpkg{} provides a key called |ml|\meta{something},
+% customization of your \matlab{} listings should be done with the latter, not
+% the former.
+%
+%
+% \subsection{Changing the font of Matlab listings}
+%
+% For compatibility reasons, the \mlpkg{} package uses the Computer Modern
+% typewriter font by default.
+% However, this font is far from ideal,
+% because it doesn't come with a boldface version,
+% and the \matlab{} editor does display some elements of \matlab{} syntax
+% (section titles) in boldface.
+% Therefore, I encourage you to switch to your preferred ``programmer font''
+% instead; how to do that depends on which typesetting engine you use.
+%
+% For |pdflatex| users,
+% \mlpkg{} conveniently provides a macro for easily selecting the Bera Mono
+% font---which is a popular monospaced font for listings,
+% and the one I used for all listings in this manual.
+%^^A
+% \begin{syntax}
+%
+%   \item[0.1] \rcmdname\mlttfamily
+%
+%     selects the Bera Mono font (somewhat scaled down).
+%
+% \end{syntax}
+%^^A
+% To use Bera Mono in your \matlab{} listings, you must pass |\mltttfamily| to
+% \lstpkg{}' \keyname{basicstyle} key (\emph{after} loading one of the three
+% styles defined by \mlpkg{}) and also---this is important---^^A
+% load the \pkg{fontenc} package with option \opt{T1}:
+%^^A
+% \begin{verbatim}
+%   \usepackage[T1]{fontenc}\end{verbatim}
+%^^A
+%
+%
+% \subsection{\mlpkg{}'s key-value interface}
+%
+% For each of the \mlpkg{} keys described below,
+% the value assigned to it in the \mlsty{Matlab-editor} style is indicated
+% on the right-hand side.
+%^^A
+% \begin{syntax}
+%
+%   \item[0.1,\color{blue}]
+%     \rkeyname{mlkeywordstyle}|=|\meta{style}
+%
+%     This key determines the style applied to \matlab{} keywords.
+%     The last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%
+%   \item[0.1,\color{black}]
+%     \rkeyname{mllastelementstyle}|=|\meta{style}
+%
+%     The |end| keyword has different meanings depending on the context in
+%     which it occurs:
+%     it may be used to close a code block (e.g.\ a while loop),
+%     or it may stand for the last element of an array.
+%     In the first case, it gets highlighted in the same style as the other
+%     \matlab{} keywords, like so: "end".
+%     In the other case, it gets highlighted like ``normal text'', like so:
+%     \overrideEnd.
+%     This key determines the style of this keyword in cases where it means
+%     ``last element''.
+%     The last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%
+%   \item[0.1,false]
+%     \rkeyname{mloverride}|=|\meta{\alternative{true,false}}
+%     \syntaxor\rkeyname{mloverride}
+%
+%     By default, in inline code, \mlpkg{} highlights the |end| keyword as
+%     the closing keyword (\emph{not} as the last-element keyword)
+%     and highlights the four class-definition identifiers as \matlab{}
+%     functions (\emph{not} as keywords), like so:
+%     "end", "events", "enumeration", "methods", and "properties".
+%     This key allows you to override the current context, so that those
+%     five context-sensitive keywords be typeset in the style of the
+%     alternative context, like so:
+%     \overrideEnd{},
+%     \overrideEvents{}, 
+%     \overrideEnumeration{},
+%     \overrideMethods{},
+%     \overrideProperties{}.
+%
+%   \item[0.1,{\color[RGB]{160,32,240}}]
+%     \rkeyname{mlstringstyle}|=|\meta{style}
+%
+%     This key determines the style applied to \matlab{} quoted and unquoted
+%     strings.
+%     The last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%
+%   \item[0.1,{\color[RGB]{34,139,34}}]
+%     \rkeyname{mlcommentstyle}|=|\meta{style}
+%
+%     This key determines the style applied to \matlab{} to-end-of-line and
+%     block comments.
+%     The last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%
+%   \item[0.1,{\bfseries\color[RGB]{34,139,34}}]
+%     \rkeyname{mlsectiontitlestyle}|=|\meta{style}
+%   
+%     This key determines the style applied to \matlab{} section titles.
+%     The last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%     
+%   \item[0.1,false]
+%     \rkeyname{mlshowsectionrules}|=|\meta{\alternative{true,false}}
+%     \syntaxor\rkeyname{mlshowsectionrules}
+%
+%     This key determines whether an horizontal rule gets printed above each
+%     \matlab{} section title.
+%
+%   \item[0.1,.05]
+%     \rkeyname{mlsectionrulethickness}|=|\meta{number}
+%     
+%     This key determines the thickness of the horizontal rule above each
+%     \matlab{} section title.
+%     The resulting thickness corresponds to the product of the value passed
+%     to this key and the length value of |\baselineskip|.
+%
+%   \item[0.1,black!15]
+%     \rkeyname{mlsectionrulecolor}|=|\meta{color}
+%
+%     This key determines the color of the horizontal rule shown above each
+%     \matlab{} section title.
+%
+%   \item[0.1,{\color[RGB]{178,140,0}}]
+%     \rkeyname{mlsyscomstyle}|=|\meta{style}
+%
+%     This key determines the style applied to \matlab{} system commands.
+%     The last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%
+%   \item[0.1]
+%     \rkeyname{mlsharedvars}|=|\meta{list of variables}
+%   \item[0.1]
+%     \rkeyname{mlmoresharedvars}|=|\meta{list of variables}
+%   \item[0.1]
+%     \rkeyname{mldeletesharedvars}|=|\meta{list of variables}
+%   \item[0.1,{\color[RGB]{0,163,163}}]
+%     \rkeyname{mlsharedvarstyle}|=|\meta{style}
+%
+%     The first three of these four keys allow you to define, add, or remove
+%     (respectively) \matlab{} variables with shared scope.
+%     The last one determines the style applied to such variables;
+%     the last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%
+%   \item[0.1]
+%     \rkeyname{mlunquotedstringdelim}|={|^^A
+%       \meta{opening delimiter}|}{|\meta{closing delimiter}|}|
+%
+%     This key allows you to define delimiters
+%     (possibly composed of multiple characters)
+%     for highlighting unquoted strings;
+%     the delimiters themselves do not get printed in the output.
+%     Be aware that the special characters |{}#%\| must be escaped with a
+%     backslash (see item~5 in subsection~4.1 of the
+%     \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}).
+%     Note that this key is only a tentative solution;
+%     automatic highlighting of unquoted strings is a planned feature for the
+%     next release of \mlpkg{}, which should make this key obsolete.
+%
+%   \item[0.1,{\rmfamily\itshape\color[RGB]{209,0,86}}]
+%     \rkeyname{mlplaceholderstyle}|=|\meta{style}
+%
+%     This key determines the style applied to placeholders in code snippets.
+%     The last token can be a one-parameter command,
+%     such as |\textbf| or |\underbar|.
+%
+%   \item[0.2,true]
+%     \rkeyname{mlscaleinline}|=|\meta{\alternative{true,false}}
+%     \syntaxor\rkeyname{mlscaleinline}
+%
+%     If this key is set, any font-size specification in the basic style is
+%     overriden, and inline \matlab{} code is scaled to it surroundings;
+%     in other words, the font size of inline \matlab{} code is made to match
+%     the local font size.
+% 
+%   \item[0.2,false]
+%     \rkeyname{mlonlyheader}|=|\meta{\alternative{true,false}}
+%     \syntaxor\rkeyname{mlonlyheader}
+%
+%     If this key is set, output is dropped after the first block of
+%     contiguous line comments, which normally corresponds to the function's
+%     header, if any.
+%
+% \end{syntax}
+%
+%
+% \section{Tips and tricks}
+%
+% Here is a list of recommendations^^A
+% ---some more opinionated than others.
+% \paragraph{Stick with the \mllng{} language.}
+% Defining a \lstpkg{} language based on \mllng{} is discouraged,
+% for the following reason:
+% \mlpkg{} performs some necessary housekeeping tasks at the beginning and
+% end of each listing, but only under the condition that the name of the
+% language used by the listing be \mllng{};
+% therefore, \matlab{} listings are unlikely to get correctly highlighted if
+% the language name differs from \mllng{}.
+%
+% \paragraph{Define your own style.}
+% For maintainability reasons, if you're not completely satisfied with any of
+% the predefined styles, you should define your own \lstpkg{} style.
+% You can even base your custom style on one of the predefined styles and
+% tweak it (see subsection~4.5 in the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}).
+%
+% \paragraph{Load the base language/style first; customize later.}
+% If you want to customize the appearance of your \matlab{} listings, 
+% you should use \lstpkg{}' \keyname{language} key or \keyname{style} key
+% before using any other (\lstpkg{} or \mlpkg{}) key,
+% because loading a language or a style ``too late'' has the potential to
+% wipe out most of the current settings.
+%
+% \paragraph{Define macros for recurring placeholders.}
+% For maintainability reasons, you should define macros for oft-used
+% placeholders, e.g.
+%^^A
+% \begin{verbatim}
+%   \newcommand\phcond{\mlplaceholder{condition}}\end{verbatim}
+%
+% \paragraph{For more highlights, use \lstpkg{}' \keyname{emph} key}
+% If you want to highlight some identifiers in \matlab{} listings, use
+% \lstpkg{}' \keyname{emph} key. Do \emph{not} use \lstpkg{}'
+% \keyname{keywords} or \keyname{morekeywords} keys.
+%
+% \paragraph{Don't copy \& paste!}
+% Do not encourage your readers to copy listings from their PDF viewer and
+% then paste them in the \matlab{} editor.
+% Unfortunately, it simply is \emph{not} a reliable way of distributing code,
+% for at least three reasons:
+%^^A
+% \begin{itemize}
+%   \item copying listings than span multiple pages of a PDF document is
+%     tedious and error-prone;
+%   \item the results of copying content from a PDF for
+%     subsequent pasting vary widely from one PDF viewer to another;
+%   \item line breaks introduced by \lstpkg{} for typesetting a \matlab{}
+%     listing may translate to invalid \matlab{} syntax, if copied and pasted
+%     \emph{verbatim}.
+% \end{itemize}
+%
+% \paragraph{Typesetting a vertically centered tilde}
+% Unfortunately, not all fonts typeset the tilde character ("~") vertically
+% centered---as it is in the \matlab{} editor.
+% Be aware that, if you set a font for your \matlab{} listings
+% (via \lstpkg{}' \keyname{basicstyle} key) that is different from \mlpkg{}'s
+% default (a scaled-down version of Bera Mono), tilde characters occuring in
+% your listings may get typeset vertically off-center.
+% Because a good, font-independent workaround seems out of reach,
+% I refer you to \url{http://tex.stackexchange.com/q/312/21891},
+% where you will find a list of ad-hoc solutions.
+%
+% \paragraph{Avoid literate replacements like the plague!}
+% The \pkg{mcode} package predefines so-called ``literate replacements''
+% (see subsection~5.4 in the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation}),
+% e.g.\ for printing~``\(\leq\)'' in place of each instance of~``"<="''.
+% I deliberately chose not to define any such literate replacements in
+% \mlpkg{} because I think that, rather than improving code readability,
+% they have a potential to confuse and mislead your readers.
+% In particular, newcomers to the programming language may not immediately
+% realize that those symbols are not part of the language's syntax;
+% they may ascribe literal meaning to them and attempt to reproduce them in
+% their editor or IDE.
+% How counterproductive!
+% Of course, if you insist, you can still define your own literate
+% replacements.
+%
+%
+% \part{Miscellaneous}
+% 
+% \section{To-do list}
+%
+% \paragraph{Automatic highlighting of unquoted strings}
+% In the current version of \mlpkg{}, unquoted strings will only be
+% highlighted as strings if you delimit them with custom delimiters
+% (defined via the \rkeyname{mlunquotedstringdelim} key).
+% However, I have plans to implement an automatic approach in a future
+% release.
+% Note that this feature will make the \rkeyname{mlunquotedstringdelim} key
+% obsolete.
+%
+% \paragraph{Increased support for \octave{}'s syntax}
+% Support for \octave{}'s idiosyncratic syntax---^^A
+% e.g. |endif| and |endwhile| keywords---^^A
+% will be added in a future release of \mlpkg{}.
+%
+%
+% \section{Missing features and known issues}
+%
+% Although \mlpkg{} does a reasonably good job at replicating the syntax
+% highlighting performed by the \matlab{} editor, some problems remain.
+% Here is a list of known, currently unresolved problems.
+% 
+% \paragraph{No automatic highlighting of variables with shared scope}
+% Unfortunately, automatic highlighting of variables with shared scope
+% would require multiple passes, which the \lstpkg{} package cannot do.
+% However, I believe that the number of variables in your \matlab{} code
+% should be small enough^^A
+% ---otherwise, your \matlab{} code is probably not sound!---^^A
+% that you can afford to highlight those variables manually, if you insist on
+% highlighting them at all.
+% 
+% \paragraph{No highlighting of unterminated strings}
+% Because \lstpkg{} cannot look very far ahead, I haven't found an easy way of
+% checking whether an opening string delimiter is missing a matching (closing)
+% string delimiter on the same line.
+%
+% \paragraph{Illegal syntax tends to yield incorrect syntax highlighting}
+% For example, the \matlab{} editor would highlight the |end| keyword in the
+% listing below, not as closing keyword ("end"), but as last-element keyword
+% (\overrideEnd{}).
+%^^A
+% \begin{lstsample}{}{\lstset{style=nonbnoframe}}
+%    \begin{lstlisting}[
+%      style=Matlab-editor,
+%      basicstyle=\mlttfamily,
+%      numbers=none]
+%    if=end
+%    \end{lstlisting}
+% \end{lstsample}
+%
+% \paragraph{Some section titles fail to be highlighted as such}
+% In \matlab{}, a line containing only ``\texttt{\%\%}'' and blank
+% characters is a section title.
+% \mlpkg{} incorrectly highlights such a line in comment style.
+%^^A
+% \begin{lstsample}{}{\lstset{style=nonbnoframe}}
+%    \begin{lstlisting}[
+%      style=Matlab-editor,
+%      numbers=none,
+%      basicstyle=\mlttfamily,
+%      numbers=none]
+%    %% This is a section title
+%    %  and so is the next line
+%    %%
+%    % but it gets highlighted
+%    % like a comment.
+%    \end{lstlisting}
+% \end{lstsample}
+%
+% \paragraph{\lstpkg{}' \keyname{keespaces} key messes up section-title rules}
+% If both \lstpkg{}' \keyname{keepspaces} and \mlpkg{}'s
+% \rkeyname{mlshowsectionrules} are set, section titles that start by some
+% white space get pushed to the right.
+%^^A
+% \begin{lstsample}{}{\lstset{style=nonbnoframe}}
+%    \begin{lstlisting}[
+%      style=Matlab-editor,
+%      basicstyle=\mlttfamily,
+%      numbers=none,
+%      keepspaces,
+%      mlshowsectionrules]
+%        %% the rule gets pushed to the right...
+%    \end{lstlisting}
+% \end{lstsample}
+% 
+% \paragraph{``Runaway'' block comments end prematurely (in some cases)} 
+% \matlab{} requires opening and closing delimiters of block comments to each
+% be on a line on its own, without any visible character, but \mlpkg{}
+% incorrectly considers block comments closed even in some cases where this
+% rule is infringed.
+% For example, in the listing below, the \matlab{} editor would typeset
+% "a = 1" in comment style.
+%^^A
+% \begin{lstsample}{}{\lstset{style=nonbnoframe}}
+%    \begin{lstlisting}[
+%      style=Matlab-editor,
+%      basicstyle=\mlttfamily,
+%      numbers=none]
+%    %{
+%      "runaway"
+%     block
+%     comment %}
+%    a = 1
+%    \end{lstlisting}
+% \end{lstsample}
+%
+%
+% \section{Bug reports and feature suggestions}
+%
+% The development version of \mlpkg{} is currently hosted on Bitbucket at
+% \href{http://bitbucket.org/Jubobs/matlab-prettifier/}
+%   {Jubobs/matlab-prettifier}.
+% If you find an issue in \mlpkg{} that this manual does not mention,
+% if you would like to see a feature implemented in the package,
+% or if you can think of ways in which the \mlpkg{} documentation could be
+% improved, please open a ticket in the Bitbucket repository's issue tracker;
+% alternatively, you can send me an email at
+% \href{mailto:jubobs.matlab.prettifier@gmail.com}
+%   {jubobs.matlab.prettifier@gmail.com}
+%
+%
+% \section{Acknowledgments}
+% Thanks to the developers of the \lstpkg{} package,
+% without which \mlpkg{} would never have existed.
+% I'm also in debt to many
+% \href{http://tex.stackexchange.com}{TeX.SX} users for their help,
+% encouragements, and suggestions.
+% Thanks in particular to David Carlisle, Marco Daniel,
+% Enrico Gregorio (egreg), Harish Kumar, Heiko Oberdiek, and Robert Schlicht.
+% Thanks also to the good people at \href{http://www.ctan.org}{CTAN}
+% for hosting the package.
+%
+%
+% \makeatletter
+% \def\index@prologue{\part{Index}\markboth{Index}{Index}}
+% \makeatother
+% \StopEventually{^^A
+%   \clearpage^^A
+%   \PrintChanges^^A
+%   \setcounter{IndexColumns}{2}^^A
+%   \PrintIndex^^A
+% }
+%
+%
+% \part{Implementation}
+%
+% Be aware that, for ``namespacing'', the \mlpkg{} package uses, not a prefix,
+% but the ``|mlpr|''~suffix (preceded by an |@| character) throughout.
+%
+%
+% \section{Preliminary checks}
+%
+% \begin{macro}{\lstoptcheck@mlpr}
+%   Because the \lstpkg{} options \opt{noaspects}, \opt{0.21}, and
+%   \opt{savemem} are incompatible with \pkg{matlab-prettifier}, checking
+%   whether the \lstpkg{} package has been loaded with any of those options is
+%   a good idea; if so, we should issue an error.
+%   This macro checks whether \lstpkg{} was loaded with a given option
+%   and, if so, throws an error.
+%    \begin{macrocode}
+\newcommand\lstoptcheck@mlpr[1]
+{%
+  \@ifpackagewith{listings}{#1}%
+  {
+    \PackageError{matlab-prettifier}%
+      {incompatible listings' option #1}%
+      {%
+        Make sure the `listings' package
+        doesn't get loaded with option `#1'%
+      }
+  }
+  {}
+}
+%    \end{macrocode}
+% \end{macro}
+% We now use this macro to make sure that none of the problematic \lstpkg{}
+% options has been passed to \lstpkg{} during an earlier loading of that
+% package.
+%    \begin{macrocode}
+\lstoptcheck@mlpr{noaspects}
+\lstoptcheck@mlpr{0.21}
+\lstoptcheck@mlpr{savemem}
+%    \end{macrocode}
+%
+%
+% \section{Package options}
+%
+% \paragraph{Framed listings}
+% \begin{macro}{\ifframed@mlpr@}
+% This option draws a frame around each listing by default.
+%    \begin{macrocode}
+\newif\ifframed@mlpr@
+\DeclareOption{framed}{\framed@mlpr@true}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Numbered lines}
+% \begin{macro}{\ifnumbered@mlpr@}
+% This option prints line numbers to the left of each listing by default.
+%    \begin{macrocode}
+\newif\ifnumbered@mlpr@
+\DeclareOption{numbered}{\numbered@mlpr@true}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Draft}
+% This option is simply passed to \lstpkg{}.
+%    \begin{macrocode}
+\DeclareOption{draft}{\PassOptionsToPackage{\CurrentOption}{listings}}
+%    \end{macrocode}
+%
+% \paragraph{Final}
+% This option is simply passed to \lstpkg{}.
+%    \begin{macrocode}
+\DeclareOption{final}{\PassOptionsToPackage{\CurrentOption}{listings}}
+%    \end{macrocode}
+%
+% \paragraph{Discard undefined options}
+% We discard any other option passed to \mlpkg{} by the user
+% and issue a warning.
+%    \begin{macrocode}
+\DeclareOption*%
+{%
+  \OptionNotUsed
+  \PackageWarning{matlab-prettifier}{Unknown `\CurrentOption' option}
+}
+%    \end{macrocode}
+% \paragraph{Process options}
+%    \begin{macrocode}
+\ProcessOptions\relax
+%    \end{macrocode}
+%
+%
+% \section{Required packages}
+% 
+% The \mlpkg{} package require three packages without any package option:
+% the \pkg{textcomp} package, in order to use \lstpkg{}' \keyname{upquote}
+% key;
+% the \pkg{xcolor} package, in order to color our \matlab{} code;
+% and, of course, the \lstpkg{} package.
+%    \begin{macrocode}
+\RequirePackage{textcomp}[2005/09/27]
+\RequirePackage{xcolor}[2007/01/21]
+\RequirePackage{listings}[2013/08/26]
+%    \end{macrocode}
+%
+%
+% \section{Definition of the \texorpdfstring{\mllng}{Matlab-pretty} language}
+%
+% \paragraph{Language name}
+% \begin{macro}{\language@mlpr}
+%   To avoid code duplication in this package file, we define a macro that
+% expands to the name of our new language, \mllng{}.
+%    \begin{macrocode}
+\newcommand\language@mlpr{Matlab-pretty}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\languageNormedDefd@mlpr}
+%   However, because \lstpkg{} ``normalizes'' language names internally,
+%   we will also need to define a macro that expands to the normalized name of
+%   the new language.
+%    \begin{macrocode}
+\expandafter\lst@NormedDef\expandafter\languageNormedDefd@mlpr%
+  \expandafter{\language@mlpr}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Language definition}
+% We can now define our new \lstpkg{} language, using some |\expandafter|
+% trickery on |\lstdefinelanguage|.
+%    \begin{macrocode}
+\expandafter\expandafter\expandafter\lstdefinelanguage\expandafter%
+{\language@mlpr}
+{%
+%    \end{macrocode}
+%
+% \paragraph{Case sensitivity}
+% \matlab{} is a case-sensitive language.
+%    \begin{macrocode}
+  sensitive=true,
+%    \end{macrocode}
+%
+% \paragraph{Forbidden characters in identifiers}
+% By default, \lstpkg{} allows ``\$'' and ``@'' to occur in identifiers,
+% but those characters are not valid \matlab{} identifiers.
+%    \begin{macrocode}
+  alsoother={\$@},
+%    \end{macrocode}
+%
+% \paragraph{Character-table adjustments}
+% In order to keep track of the context, we need to modify the character
+% table a bit.
+%    \begin{macrocode}
+  MoreSelectCharTable=\MoreSelectCharTable@mlpr,
+%    \end{macrocode}
+%
+% \paragraph{Keywords}
+%
+% The keywords defined below are based on the list returned by the
+% \matlabver{} "iskeyword" function and the four class-definition keywords^^A
+% ---which are omitted by the "iskeyword" function.
+% Because different \matlab{} keywords affect the context in different ways,
+% we use several classes of \pkg{listings} keywords to handle them.
+%
+% The following keywords open a block unrelated to class definition. 
+%    \begin{macrocode}
+  morekeywords=[1]%
+  {% 
+    for,
+    if,
+    otherwise,
+    parfor,
+    spmd,
+    switch,
+    try,
+    while,
+  },
+  keywordstyle=[1]\processOpRegKW@mlpr,
+%    \end{macrocode}
+% Most of the following keywords (nicknamed ``middle'' keywords herein) can
+% only occur within a block opened by the keywords listed above^^A
+% ---"function" and "return" are exceptions, but, as far as I can tell,
+% seem to have the same effects on syntax highlighting as the others---^^A
+% and are unrelated to class definition.
+%    \begin{macrocode}
+  morekeywords=[2]%
+  {%
+    break,
+    case,
+    catch,
+    continue,
+    else,
+    elseif,
+    function,
+    return,
+  }, 
+  keywordstyle=[2]\processMidKW@mlpr,
+%    \end{macrocode}
+% The following two keywords are ``standalone'';
+% they don't open or close any block.
+%    \begin{macrocode}
+  morekeywords=[3]%
+  {%
+    global,
+    persistent,
+  }, 
+  keywordstyle=[3]\processStdaKW@mlpr,
+%    \end{macrocode}
+% The "classdef" keyword interacts with other keywords in a unique fashion;
+% therefore, we dedicate a whole class of \lstpkg{} keywords to it. 
+%    \begin{macrocode}
+  morekeywords=[4]{classdef},  
+  keywordstyle=[4]\processClassdefKW@mlpr,
+%    \end{macrocode}
+% We dedicate a class of \lstpkg{} keywords to the four \matlab{} keywords
+% that only occur within a class-definition block,
+% namely \overrideEvents{}, \overrideEnumeration{}, \overrideMethods{},
+% and \overrideProperties{}.
+%    \begin{macrocode}
+  morekeywords=[5]%
+  {%
+    enumeration,
+    events,
+    methods,
+    properties,
+  },
+  keywordstyle=[5]\processMidClassdefKW@mlpr,
+%    \end{macrocode}
+% The |end| keyword has a very peculiar behavior and deserves its own keyword
+% class.
+%    \begin{macrocode}
+  morekeywords=[6]{end},
+  keywordstyle=[6]\processEndKW@mlpr,
+%    \end{macrocode}
+%
+% \paragraph{Strings}
+% We simply use \lstpkg{}' built-in mechanism for highlighting \matlab{}
+% quoted string\ldots with a twist; more details follow.
+%    \begin{macrocode}
+  morestring=[m]',
+  stringstyle=\processString@mlpr,
+%    \end{macrocode}
+%
+% \paragraph{Comments \& section titles}
+% Delimiters for to-end-of-line and block comments are defined below.
+%    \begin{macrocode}
+  morecomment=[l]\%,
+  morecomment=[n]{\%\{\^^M}{\%\}\^^M},
+  commentstyle=\commentStyle@mlpr,
+%    \end{macrocode}
+% The line-continuation token ("..."), which starts a to-end-of-line comment,
+% is treated separately.
+%    \begin{macrocode}
+  moredelim=**[il][\processDotDotDot@mlpr]{...},
+%    \end{macrocode}
+% Section titles, as special comments that get highlighted in a style
+% different to that of regular comments, must also be treated separately.
+%    \begin{macrocode}
+  moredelim=[l][\processSectionTitle@mlpr]{\%\%\ },
+%    \end{macrocode}
+%
+% \paragraph{System commands}
+% System commands are handled in a straightforward manner by an |l|-type
+% delimiter.
+%    \begin{macrocode}
+  moredelim=[l][\syscomStyle@mlpr]!,
+%    \end{macrocode}
+%
+% \paragraph{Required \lstpkg{} aspects} 
+% We now only need to specify the required \lstpkg{} ``aspects''.
+%    \begin{macrocode}
+}[
+  keywords,
+  strings,
+  comments,
+]
+%    \end{macrocode}
+%
+%
+% \section{State variables}
+% We define a number of \TeX{} counters and switches that will be used as
+% ``state variables'', to keep track of the context.
+%
+% \paragraph{Counters}
+% \begin{macro}{\netBracketCount@mlpr}
+% This counter is used to keep a net running count of opening and closing
+% brackets---roughly speaking.
+% When an opening bracket---be it round, square or curly---is encountered,
+% the counter is incremented;
+% conversely, when a closing bracket is encountered, the counter is
+% decremented.
+% I write ``roughly speaking'', because that counter gets reset on some
+% occasions; more details follow.
+%    \begin{macrocode}
+\newcount\netBracketCount@mlpr
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\blkLvl@mlpr}
+% This counter counter is used to keep track of the block nesting level.
+%    \begin{macrocode}
+\newcount\blkLvl@mlpr
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\blkLvlAtClassdef@mlpr}
+% This counter is used to keep track of the block nesting level at which the
+% last "classdef" keyword occured.
+%    \begin{macrocode}
+\newcount\blkLvlAtClassdef@mlpr
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Switches}
+% \begin{macro}{\ifClosingEndKW@mlpr@}
+% This switch determines whether the |end| keyword acts as a closing keyword
+% or as last-element keyword in the current context.
+%    \begin{macrocode}
+\newif\ifClosingEndKW@mlpr@    \ClosingEndKW@mlpr@true
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ifInClassdef@mlpr@}
+% This switch determines whether we're within a class-definition block or not.
+%    \begin{macrocode}
+\newif\ifInClassdef@mlpr@        \InClassdef@mlpr@false
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ifInStr@mlpr@}
+% This switch determines whether we're inside a string or not.
+%    \begin{macrocode}
+\newif\ifInStr@mlpr@                  \InStr@mlpr@false
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ifVisCharOccured@mlpr@}
+% This switch is used to keep track of whether visible characters have
+% occured on the current line.
+%    \begin{macrocode}
+\newif\ifVisCharOccured@mlpr@\VisCharOccured@mlpr@false
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ifInSecTitle@mlpr@}
+% This switch determines whether we're inside a section title or not.
+%    \begin{macrocode}
+\newif\ifInSecTitle@mlpr@        \InSecTitle@mlpr@false
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ifDroppingOutput@mlpr@}
+% This switch determines whether we're passed the first contiguous block of
+% line comments (function header).
+%    \begin{macrocode}
+\newif\ifDroppingOutput@mlpr@\DroppingOutput@mlpr@false
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Helper macros for resetting state variables}
+% The following macros are used to reset counters and switches.
+% \begin{macro}{\resetEndKW@mlpr}
+% This macro restores the |end| keyword as a closing keyword.
+%    \begin{macrocode}
+\newcommand\resetEndKW@mlpr
+{%
+  \global\ClosingEndKW@mlpr@true%
+  \global\netBracketCount@mlpr=0%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\resetClassdefKW@mlpr}
+% This macro reinitializes state variables related to class definition.
+%    \begin{macrocode}
+\newcommand\resetClassdefKW@mlpr
+{%
+  \global\InClassdef@mlpr@false%
+  \global\blkLvl@mlpr=0%
+  \global\blkLvlAtClassdef@mlpr=0%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \section{Processing of syntactic elements}
+%
+% (The overarching algorithm is not documented here;
+% in a future release, perhaps.)
+%
+% \paragraph{Processing of brackets}
+% An opening and or a closing brackets occuring in a \matlab{} listing affects
+% the context;
+% for instance, an |end| keyword is always interpreted as a closing keyword if
+% it is immediately preceded by a closing bracket, no matter what comes
+% before that.
+% To keep track of the context, we must update our state variables every time
+% a bracket is encountered.
+%
+% \begin{macro}{\MoreSelectCharTable@mlpr}
+% This macro, which is passed to \lstpkg{}' \keyname{MoreSelectCharTable} key
+% in the definition of \mllng{}, allows us to dictate what happens when a
+% bracket or a semicolon is encountered.
+%    \begin{macrocode}
+\newcommand\MoreSelectCharTable@mlpr
+{%
+%    \end{macrocode}
+%
+% \begin{macro}{\roundBktOp@mlpr}
+% We store the original definition of ``|(|'' from the default character
+% table in a dedicated macro and modify the behavior of that character.
+%    \begin{macrocode}
+  \processOpenBracket@mlpr{`(}{\roundBktOp@mlpr}%
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\squareBktOp@mlpr}
+% We store the original definition of ``|[|'' from the default character
+% table in a dedicated macro and modify the behavior of that character.
+%    \begin{macrocode}
+  \processOpenBracket@mlpr{`[}{\squareBktOp@mlpr}%
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\curlyBktOp@mlpr}
+% We store the original definition of ``|{|'' from the default character
+% table in a dedicated macro and modify the behavior of that character.
+%    \begin{macrocode}
+  \processOpenBracket@mlpr{`\{}{\curlyBktOp@mlpr}%
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\roundBktCl@mlpr}
+% We store the original definition of ``|)|'' from the default character
+% table in a dedicated macro and modify the behavior of that character.
+%    \begin{macrocode}
+  \processCloseBracket@mlpr{`)}{\roundBktCl@mlpr}%
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\squareBktCl@mlpr}
+% We store the original definition of ``|]|'' from the default character
+% table in a dedicated macro and modify the behavior of that character.
+%    \begin{macrocode}
+  \processCloseBracket@mlpr{`]}{\squareBktCl@mlpr}%
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\curlyBktCl@mlpr}
+% We store the original definition of ``|}|'' from the default character
+% table in a dedicated macro and modify the behavior of that character.
+%    \begin{macrocode}
+  \processCloseBracket@mlpr{`\}}{\curlyBktCl@mlpr}%
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\semicolon@mlpr}
+% We store the original definition of ``|;|'' from the default character
+% table in a dedicated macro and modify the behavior of that character.
+%    \begin{macrocode}
+  \processSemicolon@mlpr{`;}{\semicolon@mlpr}%
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\processOpenBracket@mlpr}
+% This macro is used to ``hook into'' opening-bracket characters and update
+% state variables every time such a character is encountered in \lstpkg{}'
+% ``processing mode''.
+%    \begin{macrocode}
+\newcommand\processOpenBracket@mlpr[2]
+{%
+  \lst@DefSaveDef{#1}#2%
+  {%
+    #2%
+    \ifnum\lst@mode=\lst@Pmode\relax%
+      \global\ClosingEndKW@mlpr@false%
+      \global\advance\netBracketCount@mlpr by \@ne%
+    \fi
+  }%  
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\processCloseBracket@mlpr}
+% This macro is used to ``hook into'' closing-bracket characters and update
+% state variables every time such a character is encountered in \lstpkg{}'
+% ``processing mode''.
+%    \begin{macrocode}
+\newcommand\processCloseBracket@mlpr[2]
+{%
+  \lst@DefSaveDef{#1}#2%
+  {%
+    #2%
+    \ifnum\lst@mode=\lst@Pmode\relax%
+      \ifClosingEndKW@mlpr@%
+        \netBracketCount@mlpr=0%
+      \else
+        \global\advance\netBracketCount@mlpr by \m@ne%
+        \ifnum\netBracketCount@mlpr>0%
+        \else
+          \global\ClosingEndKW@mlpr@true%
+        \fi
+      \fi
+    \fi
+  }%  
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\processSemicolon@mlpr}
+% This macro is used to ``hook into'' the semicolon character and update
+% state variables every time such a character is encountered in \lstpkg{}'
+% ``processing mode''.
+%    \begin{macrocode}
+\newcommand\processSemicolon@mlpr[2]
+{%
+  \lst@DefSaveDef{#1}#2%
+  {%
+    #2%
+    \ifnum\lst@mode=\lst@Pmode\relax%
+      \resetEndKW@mlpr%
+    \fi
+  }%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Processing of keywords}
+% The following macros are used for updating state variables every time a
+% keyword is encountered in \lstpkg{} ``processing mode''.
+%
+% \begin{macro}{\processOpRegKW@mlpr}
+% This macro updates state variables every time an opening keyword is
+% processed, and applies keyword style.
+%    \begin{macrocode}
+\newcommand\processOpRegKW@mlpr
+{%
+  \resetEndKW@mlpr%
+  \global\advance\blkLvl@mlpr\@ne%
+  \keywordStyle@mlpr%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\processMidKW@mlpr}
+% This macro updates state variables every time a ``middle'' keyword is
+% processed, and applies keyword style.
+%    \begin{macrocode}
+\newcommand\processMidKW@mlpr
+{%
+  \resetEndKW@mlpr%
+  \keywordStyle@mlpr%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\processStdaKW@mlpr}
+% As far as I can tell, ``standalone'' keywords and ``middle'' keywords
+% affect the context in the same way;
+% therefore, we simply reuse |\processMidKW@mlpr| here.
+%    \begin{macrocode}
+\newcommand\processStdaKW@mlpr\processMidKW@mlpr
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\processClassdefKW@mlpr}
+% This macro updates state variables every time the "classdef" keyword is
+% processed, and applies keyword style.
+%    \begin{macrocode}
+\newcommand\processClassdefKW@mlpr
+{%
+  \resetEndKW@mlpr%
+  \global\InClassdef@mlpr@true%
+  \global\blkLvlAtClassdef@mlpr=\blkLvl@mlpr%
+  \global\advance\blkLvl@mlpr\@ne%
+  \keywordStyle@mlpr%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\processMidClassdefKW@mlpr}
+% This macro updates state variables every time one of the four keywords
+% that only occur within a class-definition block is processed, and applies
+% the appropriate style.
+%    \begin{macrocode}
+\newcommand\processMidClassdefKW@mlpr
+{%
+  \ifOverridecontext@mlpr@%
+    \keywordStyle@mlpr%
+  \else
+    \ifInClassdef@mlpr@%
+      \resetEndKW@mlpr%
+      \global\advance\blkLvl@mlpr\@ne%
+      \keywordStyle@mlpr%
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\processEndKW@mlpr}
+% This macro updates state variables every time the |end| keyword is
+% processed, and applies the appropriate style.
+%    \begin{macrocode}
+\newcommand\processEndKW@mlpr
+{%
+  \ifOverridecontext@mlpr@%
+    \lastElemStyle@mlpr%
+  \else
+    \ifClosingEndKW@mlpr@%
+      \ifnum\blkLvl@mlpr>0%
+        \global\advance\blkLvl@mlpr\m@ne%
+      \fi
+      \ifnum\blkLvl@mlpr=\blkLvlAtClassdef@mlpr%
+        \global\InClassdef@mlpr@false%
+      \fi
+      \keywordStyle@mlpr%
+    \else
+      \lastElemStyle@mlpr%
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Processing of strings}
+% \begin{macro}{\processString@mlpr}
+% This macro records that a string has just started by setting the appropriate
+% switch, and applies string style.
+%    \begin{macrocode}
+\newcommand\processString@mlpr
+{%
+    \global\InStr@mlpr@true%
+    \stringStyle@mlpr%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Processing of line-continuation tokens}
+% \begin{macro}{\processDotDotDot@mlpr}
+% This macro typesets the line-continuation token in the style of our
+% \matlab{} keywords,
+% prohibits any mode changes on the rest of the current line,
+% and applies comment style to the rest of the current line.
+%    \begin{macrocode}
+\newcommand\processDotDotDot@mlpr
+{%
+  \lst@CalcLostSpaceAndOutput%
+  {\keywordStyle@mlpr...}%
+  \lst@modetrue%
+  \lst@Lmodetrue%
+  \commentStyle@mlpr%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Processing of section titles}
+% First, we need to define a few length macros in order to draw the horizontal
+% rule that \matlab{} shows (by default) above each section title.
+% \begin{macro}{\emHeight@mlpr}
+% We will use this length to store the height of the ``M'' character in the
+% current font.
+%    \begin{macrocode}
+\newlength\emHeight@mlpr
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\jayDepth@mlpr}
+% We will use this length to store the depth of letter ``j'' in the current
+% font.
+%    \begin{macrocode}
+\newlength\jayDepth@mlpr
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\sectionRuleOffset@mlpr}
+% We will use this length to store the result of our calculations for the
+% vertical offset required.
+%    \begin{macrocode}
+\newlength\sectionRuleOffset@mlpr
+%    \end{macrocode}
+% \end{macro}
+% Let's proceed\ldots
+% \begin{macro}{\processSectionTitle@mlpr}
+% This macro is invoked when a |%%| delimiter is encountered.
+%    \begin{macrocode}
+\newcommand\processSectionTitle@mlpr
+{%
+  \ifInSecTitle@mlpr@%
+    \sectionTitleStyle@mlpr%
+  \else
+%    \end{macrocode}
+% If visible characters have already been encountered before the |%%| on the
+% current line, this line is simply typeset as a to-end-of-line comment.
+%    \begin{macrocode}
+    \ifVisCharOccured@mlpr@%
+      \commentStyle@mlpr%
+%    \end{macrocode}
+% Otherwise, a section title starts here;
+% we update the relevant state variables and, if the
+% \rkeyname{mlshowsectionrules} key has been set, we draw a horizontal rule.
+%    \begin{macrocode}
+    \else % a section title is starting here
+      \global\InSecTitle@mlpr@true%
+      \resetEndKW@mlpr%
+      \ifShowSectRules@mlpr@%
+        \drawSectionRule@mlpr%
+      \fi
+      \sectionTitleStyle@mlpr%
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\drawSectionRule@mlpr}
+% This helper macro is used for drawing a horizontal rule just above the
+% current line. 
+%    \begin{macrocode}
+\newcommand\drawSectionRule@mlpr
+{%
+%    \end{macrocode}
+% We measure the height of the ``M'' character and the depth of the ``j''
+% character, which we then use to calculate the required vertical offset.
+%    \begin{macrocode}
+  \setlength\emHeight@mlpr{\fontcharht\font`M}%
+  \setlength\jayDepth@mlpr{\fontchardp\font`j}%
+  \setlength\sectionRuleOffset@mlpr%
+  {%
+    \dimexpr.5\emHeight@mlpr%
+           +.5\baselineskip%
+           -.5\jayDepth@mlpr\relax%
+  }%
+%    \end{macrocode}
+% We now draw a rule as required (color and dimensions).
+%    \begin{macrocode}
+  \bgroup%
+  \color{\sectionRuleColor@mlpr}%
+    \makebox[0em][l]%
+    {%
+      \raisebox{\sectionRuleOffset@mlpr}[0pt][0pt]%
+        {\rule{\lst@linewidth}{\sectionRuleRT@mlpr\baselineskip}}%
+    }%
+  \egroup%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \section{Hooking into \lstpkg{}' hooks}
+%
+% We apply some necessary patches in a number of \lstpkg{}' hooks;
+% but first, we define a few helper macros.
+%
+% \paragraph{Helper macros related to hooks}
+% \begin{macro}{\localFontSize@mlpr}
+% This macro will be used to save the current font size.
+%    \begin{macrocode}
+\newcommand\localFontSize@mlpr{}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\localBaselineskip@mlpr}
+% This macro will be used to save the current value of |\baselineskip|.
+%    \begin{macrocode}
+\newcommand\localBaselineskip@mlpr{}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\scaleInlineCode@mlpr}
+% This helper macro is for setting the font size of inline code to the local
+% font size (only if the \rkeyname{mlscaleinline} key is set).
+%    \begin{macrocode}
+\newcommand\scaleInlineCode@mlpr
+{%
+  \lst@ifdisplaystyle%
+  \else
+    \ifScaleInline@mlpr@%
+%    \end{macrocode}
+% We save the values of the current font size and of |\baselineskip| into our
+% dedicated macros\ldots
+%    \begin{macrocode}
+      \let\localFontSize@mlpr\f@size%
+      \let\localBaselineskip@mlpr\f@baselineskip%
+%    \end{macrocode}
+% \ldots and we use the basic style but we update the font size. 
+%    \begin{macrocode}
+      \expandafter\def\expandafter\lst@basicstyle\expandafter%
+      {%
+        \lst@basicstyle%
+        \fontsize{\localFontSize@mlpr}{\localBaselineskip@mlpr}%
+        \selectfont%
+      }%
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\dropOutputAfterHeader@mlpr}
+% This macro detects when the first block (if any) of contiguous of line
+% comments (function header) ends and drops output thereafter.
+%    \begin{macrocode}
+\newcommand\dropOutputAfterHeader@mlpr
+{%
+  \ifonlyheader@mlpr@%
+    \ifnum\lst@lineno>1%  
+      \lst@ifLmode%
+      \else
+%    \end{macrocode}
+% At this stage, the header has definitely ended.
+% If we've already begun dropping output, we don't do anything.
+%    \begin{macrocode}
+        \ifDroppingOutput@mlpr@%
+%    \end{macrocode}
+% Otherwise, we begin dropping output now and we set the switch accordingly.
+%    \begin{macrocode}
+        \else
+          \lst@EnterMode\lst@Pmode{}%
+          \lst@BeginDropOutput\lst@Pmode%
+        \fi
+        \global\DroppingOutput@mlpr@true%
+%    \end{macrocode}
+%    \begin{macrocode}
+      \fi
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{\hookname{InitVarsEOL}}
+% (See the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} 
+% for more details on this hook.)
+% \begin{macro}{\addedToInitVarsEOL@mlpr}
+% We add this macro (initially empty) to \lstpkg{}'
+% \hookname{InitVarsEOL} hook.
+%    \begin{macrocode}
+\newcommand\addedToInitVarsEOL@mlpr{}
+\lst@AddToHook{InitVarsEOL}{\addedToInitVarsEOL@mlpr}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@ddedToInitVarsEOL@mlpr}
+% The |\addedToInitVarsEOL@mlpr| macro is let to this one under certain
+% conditions (more details follow).
+%    \begin{macrocode}
+\newcommand\@ddedToInitVarsEOL@mlpr
+{%
+%    \end{macrocode}
+% \lstpkg{}' built-in mechanism for handling \matlab{} string does not cover
+% the illegal case in which an opening string delimiter is not followed by
+% any matching (closing) string delimiter on the same line.
+% More specifically, \lstpkg{} incorrectly highlights such a broken string
+% literal as a bona-fide \matlab{} string.
+% We improve the situation somewhat, by only highlighting as a string the line
+% containing the unmatched opening delimiter, not the lines that follow it:
+%    \begin{macrocode}
+  \ifInStr@mlpr@%
+    \global\InStr@mlpr@false%
+    \lst@LeaveMode%
+  \fi
+%    \end{macrocode}
+% Clearly, at the very beginning of a line, we're not (not yet, anyway)
+% within a section title, and no visible character has yet occured on that
+% line.
+%    \begin{macrocode}
+  \global\InSecTitle@mlpr@false%
+  \global\VisCharOccured@mlpr@false%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{\hookname{EndGroup}}
+% (See the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} 
+% for more details on this hook.)
+% \begin{macro}{\addedToEndGroup@mlpr}
+% We add this macro (initially empty) to \lstpkg{}'
+% \hookname{EndGroup} hook.
+%    \begin{macrocode}
+\newcommand\addedToEndGroup@mlpr{}
+\lst@AddToHook{EndGroup}{\addedToEndGroup@mlpr}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@ddedToEndGroup@mlpr}
+% The |\addedToEndGroup@mlpr| macro is let to this one under certain
+% conditions (more details follow).
+% If we were in a string before when \hookname{EndGroup} hook was called,
+% we're now exiting it;
+% therefore, the relevant switch must be reset.
+%    \begin{macrocode}
+\newcommand\@ddedToEndGroup@mlpr{\global\InStr@mlpr@false}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{\hookname{PostOutput}}
+% (See the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} 
+% for more details on this hook.)
+% \begin{macro}{\addedToPostOutput@mlpr}
+% We add this macro (initially empty) to \lstpkg{}'
+% \hookname{PostOutput} hook.
+%    \begin{macrocode}
+\newcommand\addedToPostOutput@mlpr{}
+\lst@AddToHook{PostOutput}{\addedToPostOutput@mlpr}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@ddedToPostOutput@mlpr}
+% The |\addedToPostOutput@mlpr| macro is let to this one under certain
+% conditions (more details follow).
+% If the last processed character was not white space
+% (this check is necessary if \lstpkg{}' \keyname{keepspaces} key is set),
+% we set the relevant switch.
+%    \begin{macrocode}
+\newcommand\@ddedToPostOutput@mlpr
+{%
+  \lst@ifwhitespace%
+  \else
+    \global\VisCharOccured@mlpr@true%
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{\hookname{Output}}
+% (See the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} 
+% for more details on this hook.)
+% \begin{macro}{\addedToOutput@mlpr}
+% We add this macro (initially empty) to \lstpkg{}'
+% \hookname{Output} hook.
+%    \begin{macrocode}
+\newcommand\addedToOutput@mlpr{}
+\lst@AddToHook{Output}{\addedToOutput@mlpr}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@ddedToOutput@mlpr}
+% The |\addedToOutput@mlpr| macro is let to this one under certain
+% conditions (more details follow).
+% If the \rkeyname{mlonlyheader} is set, we begin dropping output as soon as
+% we detect that the first contiguous block of line comments has been passed.
+%    \begin{macrocode}
+\newcommand\@ddedToOutput@mlpr{\dropOutputAfterHeader@mlpr}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \paragraph{\hookname{OutputOther}}
+% (See the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} 
+% for more details on this hook.)
+% \begin{macro}{\addedToOutputOther@mlpr}
+% We add this macro (initially empty) to \lstpkg{}'
+% \hookname{OutputOther} hook.
+%    \begin{macrocode}
+\newcommand\addedToOutputOther@mlpr{}
+\lst@AddToHook{OutputOther}{\addedToOutputOther@mlpr}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@ddedToOutputOther@mlpr}
+% The |\addedToOutputOther@mlpr| macro is let to this one under certain
+% conditions (more details follow).
+% If the \rkeyname{mlonlyheader} is set, we begin dropping output as soon as
+% we detect that the first contiguous block of line comments has been passed.
+%    \begin{macrocode}
+\newcommand\@ddedToOutputOther@mlpr{\dropOutputAfterHeader@mlpr}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{\hookname{PreInit}}
+% (See the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} 
+% for more details on this hook.)
+% Because the |\lst@AddToHook| affects hooks globally
+% (i.e.\ for all listings),
+% we must apply our patches only when required, i.e.\ 
+% in listings that use \mllng{}, and not in others.
+% The \hookname{PreInit}, which is called at the very beginning of each
+% listing, is where we do that.
+% \begin{macro}{\addedToPreInitHook@mlpr}
+% In this macro, which we add to \lstpkg{}' \hookname{PreInit} hook, we check
+% whether |\lst@language| and |\languageNormedDefd@mlpr| expand (once) to the
+% same replacement text and only apply our patches under that condition.
+%    \begin{macrocode}
+\newcommand\addedToPreInitHook@mlpr
+{%
+  \ifx\lst@language\languageNormedDefd@mlpr%
+    \scaleInlineCode@mlpr%
+    \renewcommand\addedToInitVarsEOL@mlpr\@ddedToInitVarsEOL@mlpr%
+    \renewcommand\addedToEndGroup@mlpr\@ddedToEndGroup@mlpr%
+    \renewcommand\addedToPostOutput@mlpr\@ddedToPostOutput@mlpr%
+    \renewcommand\addedToOutput@mlpr\@ddedToOutput@mlpr%
+    \renewcommand\addedToOutputOther@mlpr\@ddedToOutputOther@mlpr%
+    \DroppingOutput@mlpr@false%
+\fi
+}
+\lst@AddToHook{PreInit}{\addedToPreInitHook@mlpr}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{\hookname{DeInit}}
+% (See the
+% \href{http://www.ctan.org/pkg/listings}{\lstpkg{} documentation} 
+% for more details on this hook.)
+% In the \hookname{DeInit} hook, which is called at the very end of each
+% listing, we carry out some housekeeping tasks if the current listing uses
+% \mllng{}.
+% \begin{macro}{\addedToDeInitHook@mlpr}
+% In this macro, which we add to \lstpkg{}' \hookname{DeInit} hook, we check
+% whether |\lst@language| and |\languageNormedDefd@mlpr| expand (once) to the
+% same replacement text and, under that condition, we reset all state
+% variables.
+%    \begin{macrocode}
+\newcommand\addedToDeInitHook@mlpr
+{%
+  \ifx\lst@language\languageNormedDefd@mlpr%
+    \resetEndKW@mlpr%
+    \resetClassdefKW@mlpr%
+    \global\InStr@mlpr@false%
+    \global\VisCharOccured@mlpr@false%
+    \global\InSecTitle@mlpr@false%
+    \global\DroppingOutput@mlpr@false%
+  \fi
+}
+\lst@AddToHook{DeInit}{\addedToDeInitHook@mlpr}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \section{Key-value interface}
+%
+% We extend \lstpkg{}' key-value interface by defining several additional
+% keys, which we will use to define three \lstpkg{} styles, and which will
+% allow the user to customize the style of their \matlab{} listings,
+% should they which to do so.
+% All \mlpkg{} keys are prefixed by~``|ml|'', so that the user can easily
+% distinguish them from ``native'' \lstpkg{} keys.
+%
+% \paragraph{Keywords}
+% \begin{lstkey}{mlkeywordstyle}
+% \begin{macro}{\keywordStyle@mlpr}
+%   In the definition of \mllng{}, we used several classes of \lstpkg{}
+%   keywords to handle the different \matlab{} keywords;
+%   here is a style key to ``rule them all''.
+%    \begin{macrocode}
+\newcommand\keywordStyle@mlpr{}
+\lst@Key{mlkeywordstyle}\relax%
+  {\renewcommand\keywordStyle@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \begin{lstkey}{mllastelementstyle}
+% \begin{macro}{\lastElemStyle@mlpr}
+%   This key determines the style applied to the last-element keyword.
+%    \begin{macrocode}
+\newcommand\lastElemStyle@mlpr{}
+\lst@Key{mllastelementstyle}\relax%
+  {\renewcommand\lastElemStyle@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \begin{lstkey}{mloverride}
+% \begin{macro}{\ifOverridecontext@mlpr@}
+%   This key overrides the current context, so that context-sensitive
+%   keywords be typeset in the style associated with the alternative context.
+%    \begin{macrocode}
+\lst@Key{mloverride}{false}[t]%
+  {\lstKV@SetIf{#1}\ifOverridecontext@mlpr@}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \paragraph{Strings}
+% \begin{lstkey}{mlstringstyle}
+% \begin{macro}{\stringStyle@mlpr}
+%   This key determines the style applied to \matlab{} (quoted and unquoted)
+%   strings.
+%    \begin{macrocode}
+\newcommand\stringStyle@mlpr{}
+\lst@Key{mlstringstyle}\relax%
+  {\renewcommand\stringStyle@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \paragraph{Comments}
+% \begin{lstkey}{mlcommentstyle}
+% \begin{macro}{\commentStyle@mlpr}
+%   This key determines the style applied to \matlab{}
+%   (to-end-of-line and block) comments.
+%    \begin{macrocode}
+\newcommand\commentStyle@mlpr{}
+\lst@Key{mlcommentstyle}\relax%
+  {\renewcommand\commentStyle@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \paragraph{Section titles}
+% \begin{lstkey}{mlsectiontitlestyle}
+% \begin{macro}{\sectionTitleStyle@mlpr}
+%   This key determines the style applied to \matlab{} section titles.
+%    \begin{macrocode}
+\newcommand\sectionTitleStyle@mlpr{}
+\lst@Key{mlsectiontitlestyle}\relax
+  {\renewcommand\sectionTitleStyle@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \begin{lstkey}{mlshowsectionrules}
+% \begin{macro}{\ifShowSectRules@mlpr@}
+%   This key determines whether an horizontal rule gets printed above each
+%   section title.
+%    \begin{macrocode}
+\lst@Key{mlshowsectionrules}{false}[t]%
+  {\lstKV@SetIf{#1}\ifShowSectRules@mlpr@}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \begin{lstkey}{mlsectionrulethickness}
+% \begin{macro}{\sectionRuleRT@mlpr}
+%   This key determines the relative thickness of the horizontal rule that
+%   gets printed above each section title.
+%    \begin{macrocode}
+\newcommand\sectionRuleRT@mlpr{.05}
+\lst@Key{mlsectionrulethickness}\relax%
+  {\renewcommand\sectionRuleRT@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \begin{lstkey}{mlsectionrulecolor}
+% \begin{macro}{\sectionRuleColor@mlpr}
+%   This key determines the color of the horizontal rule that gets printed
+%   above each section title.
+%    \begin{macrocode}
+\newcommand\sectionRuleColor@mlpr{black!15}
+\lst@Key{mlsectionrulecolor}\relax%
+  {\renewcommand\sectionRuleColor@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \paragraph{System commands}
+% \begin{lstkey}{mlsyscomstyle}
+% \begin{macro}{\syscomStyle@mlpr}
+%   This key determines the style applied to system commands.
+%    \begin{macrocode}
+\newcommand\syscomStyle@mlpr{}
+\lst@Key{mlsyscomstyle}\relax%
+  {\renewcommand\syscomStyle@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \paragraph{Variables with shared scope}
+% For convenience, we create a brand new class of \lstpkg{} keywords for
+% allowing the user to define \matlab{} variables with shared scope.
+%
+% \begin{macro}{\InstallKeywords@mlpr}
+%   This helper macro (which is based on \lstpkg{}' |\lst@InstallKeywords|),
+%   will let us defines four keys in one go, all prefixed by |ml|.
+%    \begin{macrocode}
+\gdef\InstallKeywords@mlpr#1#2#3#4#5%
+{%
+  \lst@Key{ml#2}\relax
+    {\lst@UseFamily{#2}[\@ne]##1\relax\lst@MakeKeywords}%
+  \lst@Key{mlmore#2}\relax
+    {\lst@UseFamily{#2}[\@ne]##1\relax\lst@MakeMoreKeywords}%
+  \lst@Key{mldelete#2}\relax
+    {\lst@UseFamily{#2}[\@ne]##1\relax\lst@DeleteKeywords}%
+  \ifx\@empty#3\@empty\else
+     \lst@Key{#3}{#4}{\@namedef{lst@#3}{##1}}%
+  \fi
+  \expandafter\lst@InstallFamily@
+     \csname\@lst @#2@data\expandafter\endcsname
+     \csname\@lst @#5\endcsname {#1}{#2}{#3}
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{lstkey}{mlsharedvars}
+% \begin{lstkey}{mlmoresharedvars}
+% \begin{lstkey}{mldeletesharedvars}
+% \begin{lstkey}{mlsharedvarstyle}
+%   We now use |\InstallKeywords@mlpr| to define the four keys in question:
+%   \rkeyname{mlsharedvars}, which can be used to define a list of \matlab{}
+%   variables with shared scope;
+%   \rkeyname{mlmoresharedvars}, which can be used to add elements to the
+%   current list of such variables;
+%   \rkeyname{mldeletesharedvars}, which can be used to remove elements
+%   from that list;
+%   and \rkeyname{mlsharedvarstyle}, which determines the style applied to
+%   variables with shared scope.
+%    \begin{macrocode}
+\InstallKeywords@mlpr k{sharedvars}{mlsharedvarstyle}\relax%
+  {mlsharedvarstyle}{}ld
+%    \end{macrocode}
+% \end{lstkey}
+% \end{lstkey}
+% \end{lstkey}
+% \end{lstkey}
+%
+% \paragraph{Delimiters for unquoted strings}
+% \begin{lstkey}{mlunquotedstringdelim}
+%   This key allows the user to define custom delimiters^^A
+%   ---which do not get printed in the output---^^A
+%   for unquoted strings.
+%    \begin{macrocode}
+\lst@Key{mlunquotedstringdelim}\relax%
+  {\lst@DelimKey\relax{[is][\stringStyle@mlpr]{#1}}}
+%    \end{macrocode}
+% \end{lstkey}
+%
+% \paragraph{Placeholders}
+% \begin{lstkey}{mlplaceholderstyle}
+% \begin{macro}{\phStyle@mlpr}
+%   This key determines the style applied to placeholder content;
+%   the color of placeholder delimiters is designed to match that of
+%   placeholder content.
+%    \begin{macrocode}
+\newcommand\phStyle@mlpr{}
+\lst@Key{mlplaceholderstyle}\relax%
+  {\renewcommand\phStyle@mlpr{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \mlpkg{} currently does not offer a nice interface for customizing
+% code-snippet placeholder delimiters; in a future release, perhaps.
+%
+% \paragraph{Automatic scaling of inline code}
+% \begin{lstkey}{mlscaleinline}
+% \begin{macro}{\ifScaleInline@mlpr@}
+%   This key determines whether the font size of inline \matlab{} code should
+%   match the local font size.
+%    \begin{macrocode}
+\lst@Key{mlscaleinline}{true}[t]%
+  {\lstKV@SetIf{#1}\ifScaleInline@mlpr@}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+% \paragraph{Printing only a function's signature and header}
+% \begin{lstkey}{mlonlyheader}
+% \begin{macro}{\ifonlyheader@mlpr@}
+%   This key determines whether output is dropped after the first block of
+%   contiguous line comments.
+%    \begin{macrocode}
+\lst@Key{mlonlyheader}{false}[t]%
+  {\lstKV@SetIf{#1}\ifonlyheader@mlpr@}
+%    \end{macrocode}
+% \end{macro}
+% \end{lstkey}
+%
+%
+% \section{Two user-level macros}
+%
+% \begin{macro}{\mlttfamily}
+% This user-level macro can be used for selecting a scaled version of the
+% Bera Mono font, a typewriter font family which, contrary to typewriter
+% \TeX{} fonts, conveniently comes with a boldface version.
+%    \begin{macrocode}
+\newcommand\mlttfamily
+{%
+  \def\fvm@Scale{.85}%
+  \fontfamily{fvm}\selectfont%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \paragraph{Code-snippet placeholders}
+% \begin{macro}{\mlplaceholder}
+% This user-level macro can be used to typeset placeholders in code snippets.
+%    \begin{macrocode}
+\newcommand\mlplaceholder[1]
+{%
+  \bgroup%
+    \phStyle@mlpr%
+    \bgroup%
+      \phDelimStyle@mlpr%
+      \phOpDelim@mlpr%
+    \egroup%
+    #1\itcorr@mlpr%
+    \bgroup%
+      \phDelimStyle@mlpr%
+      \phClDelim@mlpr%
+    \egroup%
+  \egroup%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% 
+% \section{Other helper macros}
+%
+%    \begin{macrocode}
+\newcommand\phDelimStyle@mlpr{\rmfamily\upshape}
+%    \end{macrocode}
+%    \begin{macrocode}
+\newcommand\phOpDelim@mlpr{\textlangle}
+%    \end{macrocode}
+%    \begin{macrocode}
+\newcommand\phClDelim@mlpr{\textrangle}
+%    \end{macrocode}
+%
+% \begin{macro}{\itcorr@mlpr}
+% This macro is used for applying italic correction in case the current font
+% shape is either italic or slanted.
+%    \begin{macrocode}
+\newcommand\itcorr@mlpr
+{%
+%    \end{macrocode}
+% We define a (long) macro that expands (once) to the current font shape,
+% for comparison purposes.
+%    \begin{macrocode}
+  \expandafter\newcommand\expandafter\long@f@shape@mlpr%
+    \expandafter{\f@shape}%
+%    \end{macrocode}
+% If the current font shape is either italic or slanted, we apply italic
+% correction.
+%    \begin{macrocode}
+  \ifx\long@f@shape@mlpr\itdefault%
+    \/%
+  \else
+    \ifx\long@f@shape@mlpr\sldefault%
+      \/%
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \section{\texorpdfstring{\mlpkg{}}{matlab-prettifier} styles}
+%
+% We now define three \lstpkg{} styles for \matlab{} listings.
+%
+% \paragraph{Base style}
+%
+% This style is used internally to define the three user-level styles.
+% It's not meant to be used outside this package file.
+% \begin{macro}{\toks@mlpr}
+% We allocate a token list register in which we store settings that we'll use
+% to define the style.
+%    \begin{macrocode}
+\newtoks\toks@mlpr
+\toks@mlpr=%
+{
+  language               = \languageNormedDefd@mlpr,
+  basicstyle             = \color{black}\ttfamily\normalsize,
+  breaklines             = true,
+  showspaces             = false,
+  showstringspaces       = false,
+  upquote                = true,
+  rulecolor              = \color{black!67},
+  numberstyle            = \color{black!33},
+  mlscaleinline          = true,
+  mlonlyheader           = false,
+}
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
+\ifframed@mlpr@
+  \toks@mlpr=\expandafter{\the\toks@mlpr frame=single,}
+\fi
+\ifnumbered@mlpr@
+  \toks@mlpr=\expandafter{\the\toks@mlpr numbers=left,}
+\fi
+\begingroup\edef\@tempa{\endgroup
+  \noexpand\lstdefinestyle{MatlabBaseStyle@mlpr}{\the\toks@mlpr}
+}\@tempa
+%    \end{macrocode}
+%
+% \paragraph{Standard style}
+% Standard style of the \matlab{} editor.
+% \begin{macro}{\mlbwphstyle}^^A FIXME: to be documented
+% This user macro holds the placeholder style used in the
+% \mlsty{Matlab-editor} style.
+%    \begin{macrocode}
+\newcommand\mleditorphstyle{\color[RGB]{209,000,086}\rmfamily\itshape}
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
+\lstdefinestyle{Matlab-editor}
+{
+  style               = MatlabBaseStyle@mlpr,
+  mllastelementstyle  = \color{black}                    ,
+  mlkeywordstyle      = \color[RGB]{000,000,255}         ,
+  mlcommentstyle      = \color[RGB]{034,139,034}         ,
+  mlstringstyle       = \color[RGB]{160,032,240}         ,
+  mlsyscomstyle       = \color[RGB]{178,140,000}         ,
+  mlsectiontitlestyle = \commentStyle@mlpr      \bfseries,
+  mlsharedvarstyle    = \color[RGB]{000,163,163}         ,
+  mlplaceholderstyle  = \mleditorphstyle,
+}
+%    \end{macrocode}
+%
+% \paragraph{Black \& white style}
+% Black \& white, printer-friendly style.
+% \begin{macro}{\mlbwphstyle}^^A FIXME: to be documented
+% This user macro holds the placeholder style used in the
+% \mlsty{Matlab-bw} style.
+%    \begin{macrocode}
+\newcommand\mlbwphstyle{\color[gray]{0}\rmfamily\itshape}
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
+\lstdefinestyle{Matlab-bw}
+{
+  style               = MatlabBaseStyle@mlpr,
+  mlkeywordstyle      = \color[gray]{0}  \bfseries        ,
+  mlcommentstyle      = \color[gray]{.75}         \itshape,
+  mlstringstyle       = \color[gray]{.5}                  ,
+  mlsyscomstyle       = \color[gray]{.25}                 ,
+  mlsectiontitlestyle = \color[gray]{.75}\bfseries\itshape,
+  mlsharedvarstyle    = \color[gray]{0}                   ,
+  mlplaceholderstyle  = \mlbwphstyle,
+}
+%    \end{macrocode}
+%
+% \paragraph{Style of Pygments' MatlabLexer}
+% Style that closely mimics that of Pygments' `MatlabLexer'.
+% \begin{macro}{\mlpyglikephstyle}^^A FIXME: to be documented
+% This user macro holds the placeholder style used in the
+% \mlsty{Matlab-Pyglike} style.
+%    \begin{macrocode}
+\newcommand\mlpyglikephstyle{\color[RGB]{127,063,127}\rmfamily\itshape}
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
+\lstdefinestyle{Matlab-Pyglike}
+{
+  style               = MatlabBaseStyle@mlpr,
+  mllastelementstyle  = \color[RGB]{127,000,000}                 ,
+  mlkeywordstyle      = \color[RGB]{000,127,000}\bfseries        ,
+  mlcommentstyle      = \color[RGB]{063,127,127}         \itshape,
+  mlstringstyle       = \color[RGB]{186,034,034}                 ,
+  mlsyscomstyle       = \color[RGB]{000,127,000}                 ,
+  mlsectiontitlestyle = \color[RGB]{063,127,127}         \itshape,
+  mlsharedvarstyle    = \color[RGB]{034,034,186}                 ,
+  mlplaceholderstyle  = \mlpyglikephstyle,
+}
+%    \end{macrocode}
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/matlab-prettifier/matlab-prettifier.ins b/Master/texmf-dist/source/latex/matlab-prettifier/matlab-prettifier.ins
new file mode 100644
index 00000000000..e1a37493da2
--- /dev/null
+++ b/Master/texmf-dist/source/latex/matlab-prettifier/matlab-prettifier.ins
@@ -0,0 +1,66 @@
+%%
+%% Copyright (C) 2014 by Julien Cretel <jubobs.matlab.prettifier at gmail.com>
+%%
+%% This work may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.3
+%% of this license or (at your option) any later version.
+%% The latest version of this license is in
+%%
+%%     http://www.latex-project.org/lppl.txt
+%%
+%% and version 1.3 or later is part of all distributions of LaTeX
+%% version 2005/12/01 or later.
+%%
+%%
+% This file requires docstrip version 2.4 available from
+% ftp.dante.de tex-archive/macros/latex/unpacked/docstrip.tex
+\input docstrip
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2014 by Julien Cretel <jubobs.matlab.prettifier at gmail.com>
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+
+    http://www.latex-project.org/lppl.txt
+
+and version 1.3 or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status `maintained'.
+ 
+The Current Maintainer of this work is Julien Cretel.
+
+This work currently consists of the files matlab-prettifier.dtx,
+matlab-prettifier.ins, and the derived file matlab-prettifier.sty.
+
+\endpreamble
+
+
+\keepsilent
+\askforoverwritefalse
+
+\usedir{tex/latex/matlab-prettifier}
+
+% the package
+\generate{\file{matlab-prettifier.sty}{\from{matlab-prettifier.dtx}{package}}}
+
+% message
+\obeyspaces
+\Msg{****************************************************}
+\Msg{*                                                  *}
+\Msg{* To finish the installation you have to move the  *}
+\Msg{* following file into a directory searched by TeX: *}
+\Msg{*                                                  *}
+\Msg{*     matlab-prettifier.sty                        *}
+\Msg{*                                                  *} 
+\Msg{* To produce the documentation run the file        *}
+\Msg{* matlab-prettifier.dtx through LaTeX.             *}
+\Msg{*                                                  *}
+\Msg{****************************************************}
+
+\endbatchfile