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.

Leave a Reply

Your email address will not be published. Required fields are marked *