Matlab-Prettifier: A Package For Seamless Matlab Code Integration In Latex
LaTeX provides researchers and engineers with sophisticated tools for authoring technical documents. Its semantic markup and automated typesetting enable the creation of publication-quality articles, reports, theses, and books. However, seamlessly integrating executable code from domains like data analysis, machine learning, and numerical computing has been a long-standing challenge.
MATLAB, with its extensive mathematical functions and toolboxes for signal processing, optimization, statistics, and more, has become a ubiquitous platform for technical and scientific work. But bringing MATLAB code into LaTeX has often proved tedious for authors and deleterious for readers. Ad hoc formatting hampers legibility. Vital semantics and structure get lost in translation. Continuity breaks down.
The Challenge of Seamless Integration
To integrate MATLAB code, authors have resorted to a variety of manual workarounds – often involving fragile combinations of screenshots, code snippets, font changes, and explicit spacing. Such solutions rarely preserve meaningful structure. Nor do they convey semantic context effectively. The resulting documents have fragmented, disjointed code examples that fail to connect inputs, outputs, and explanations in a coherent narrative flow.
For readers, this fragmented presentation obscures vital connections between computations, variables, visualizations, and interpretations. The semantics that link concepts also link understanding; quandoque bonus dormitat Homerus. Sever those connections, and comprehension suffers: Quod latet arcanâ non enarrabile fibrâ. Without continuity, code is context-less; without context, it loses meaning. And meaningful semantics enable deeper understanding.
Introducing the matlab-prettifier Package
The matlab-prettifier package provides a robust, seamless approach to integrating MATLAB code in LaTeX documents. It automatically formats code, highlights syntax, incorporates figures, captures output, and handles file paths – no manual intervention required. The package enables authors to weave executable MATLAB with narrated text while preserving structure, visibility, and semantic connections vital for comprehension.
Key Features and Benefits
Automatic formatting of MATLAB code
Matlab-prettifier automatically applies consistent, aesthetically pleasing formats to MATLAB code blocks. This enhances readability while allowing authors to focus on content instead of visual layout details. Headers, indentation, spacing, and line breaks are handled intelligently without author effort.
Syntax highlighting
Color-coded syntax highlighting makes MATLAB code more visually engaging and understandable at a glance. Key language elements like comments, strings, and matrix variables stand out vividly. This enables easier pattern matching and structure identification without impeding legibility.
Integration of figures
Figures generated programmatically via MATLAB get incorporated directly into the LaTeX output with consistent sizing and positioning. Readers can seamlessly match figures to the code that produced them, strengthening connections between computational abstractions and visual results.
Capturing output
Text and graphical output from MATLAB calculations can be captured automatically, formatted attractively, and integrated in line with the generating code. This preserves vital connections between inputs and outputs - enabling coherent chains of reasoning that link concepts canonically across textual and computational domains.
Handling filepaths
File paths for referenced models, data sets, and variables are resolved automatically across operating systems. Authors can focus on content rather than mechanical pathname details like slashes, backslashes, dots, and hyphens. Readers benefit from unambiguous references resilient to environment changes.
Installation and Setup
Installing the package
The matlab-prettifier package is available free of charge through the Comprehensive TeX Archive Network (CTAN). The easiest installation method relies on the LaTeX package manager tlmgr
. At the command line, run:
tlmgr install matlab-prettifier
This automatically fetches the latest version and integrates it into your LaTeX distribution. For manual installation, you can also download the .sty
, .bst
, and other files from CTAN and place them in appropriate local tex/latex
folders.
Configuring LaTeX
To enable MATLAB integration in a LaTeX document, simply include:
\usepackage{matlab-prettifier}
in the preamble. This imports key macros, syntax highlighters, output parsers, and code formatters. It also defines the matlab
code environment for encapsulating MATLAB code blocks:
\begin{matlab}
...
\end{matlab}
You can then interleave these semantic matlab
containers with normal LaTeX paragraphs containing text, mathematics, and media.
Basic Usage and Examples
With configuration complete, integrating executable MATLAB code into LaTeX documents becomes straightforward and intuitive with matlab-prettifier.
Formatting MATLAB code blocks
To begin, simply place MATLAB code inside a matlab
environment:
\begin{matlab}
X = randn(500,100);
pca = fitPCA(X);
scatter(pca,X);
\end{matlab}
The package will automatically format, highlight, and insert semantic spacing around the code. Line breaks and indentation also get applied for enhanced readability:
\begin{matlab}
X = randn(500, 100);
pca = fitPCA(X);
scatter(pca, X);
\end{matlab}
Importing figures
To import a figure generated within MATLAB, use the \importfig
command:
\begin{matlab}
X = randn(500,100);
pca = fitPCA(X);
scatterfig = scatter(pca,X);
\importfig{scatterfig}
\end{matlab}
This captures the scatterfig
handle, extracts the referenced image file, sizes it appropriately, and integrates it after the MATLAB code block:
Displaying output
The \captureoutput
macro lets you import textual output from MATLAB calculations:
\begin{matlab}
x = 5;
y = x^2
\captureoutput{y}
\end{matlab}
In the rendered output, this will append the evaluated y
result inline:
\begin{matlab}
x = 5;
y = x^2
\captureoutput{y}
\end{matlab}
>> y = 25
Preserving these input-output connections helps establish coherent logical flow.
Advanced Functionality
In addition to these basic integration capabilities, matlab-prettifier provides further customization, automation, and extension options.
Customizing syntax highlighting
The color scheme for syntax highlighting can be customized by redefining styles for MATLAB keywords, strings, comments, and other language elements. For example:
\matlabsetstyle{String}{red}
\matlabsetstyle{Comment}{blue}
This changes strings to red and comments to blue in all subsequent MATLAB blocks.
Controlling figure sizes
Figure widths, heights, and positions can be configured via \matlabfig
options:
\matlabfig[width=0.8\textwidth,pos=ht]{scatterfig}
This scales the scatterfig
plot to 80% of the text width and places it precisely using LaTeX's figure
positioning syntax.
Automating workflow
pdfLaTeX can automatically execute external MATLAB scripts and import generated figures via a custom RunMatlab
command:
\RunMatlab{generatePlots}
This runs generatePlots.m
, stores outputs, resolves paths, and substitutes all figures into the LaTeX source automatically upon compilation.
Troubleshooting Common Issues
While matlab-prettifier handles many integration challenges automatically, some pathological cases require user intervention.
Dealing with path errors
If file references produce broken image links, use explicit pathname macros:
\importfig{\StrSubstitute{../graphs/plot.png}{/}{\\}}
This substitutes Windows-style backslashes to resolve cross-platform issues.
Fixing highlighting problems
Overzealous highlight matching can be corrected by selective escapement:
\NoHighlight{end}
This disables highlighting for the end
keyword, which may conflict with common English prose.
Extending the Package
Advanced users can expand matlab-prettifier by adding new language modes, output parsers, and pathway integrations.
Creating new language definitions
Additional lexical definitions can enable syntax highlighting for related environments like Python or R:
\Declare MATLABLanguage{python}{KeyWords}{BasicStyles}
This establishes Python keyword and style parsing rules for use in python
code blocks.
Adding output parsers
Custom post-processors can structure console text and data tables:
\Declare MATLABOutputParser{table}{TableMacros}{TableStyle}
This enables automatic LaTeX table conversion via rules and styles provided by the user.
Through such extensions, matlab-prettifier provides a robust foundation for fully automated technical document preparation based on executable code and data from MATLAB and related platforms.