Publishing Markup

Markup Overview

This section describes how to mark up your MATLAB® files so that the code appears polished when publishing. You can single-source your MATLAB code with documentation that describes its purpose.

You insert markup three different ways:

  • Use the formatting buttons and drop-down menus on the Publish tab to format the file. This method automatically inserts the text markup for you.

  • Select markup from the Insert Text Markup list in the right click menu.

  • Type the markup directly in the comments.

The following table provides a summary of the text markup options. Refer to this table if you are not using the MATLAB Editor, or if you do not want to use the Publish tab to apply the markup.

    Note:   When working with markup:

    • Spaces following the comment symbols (%) often determine the format of the texts that follows.

    • Starting new markup often requires preceding blank comment lines, as shown in examples.

    • Markup only works in comments that immediately follow a section break.

Result in OutputExample of Corresponding File Markup
Sections and Section Titles
%% SECTION TITLE
% DESCRIPTIVE TEXT
%%% SECTION TITLE WITHOUT SECTION BREAK
% DESCRIPTIVE TEXT
Text Formatting
% _ITALIC TEXT_
% *BOLD TEXT*
% |MONOSPACED TEXT|
% Trademarks:
% TEXT(TM)
% TEXT(R)
Bulleted and Numbered Lists
%% Bulleted List
%
% * BULLETED ITEM 1
% * BULLETED ITEM 2
%
%% Numbered List
%
% # NUMBERED ITEM 1
% # NUMBERED ITEM 2
%
Text and Code Blocks
%% 
% 
%  PREFORMATTED
%  TEXT
% 
%% MATLAB(R) Code
% 
%   for i = 1:10
%       disp x
%   end
% 
External Graphics
% 
% <<FILENAME.PNG>>
%
Image Snapshotsnapnow;
LaTeX Equations
%% Inline Expression
% $x^2+e^{\pi i}$
%% Block Equation
% $$e^{\pi i} + 1 = 0$$
Hyperlinks
% <http://www.mathworks.com MathWorks> 
% <matlab:FUNCTION DISPLAYED_TEXT>
HTML Markup
%
% <html>
% <table border=1><tr>
% <td>one</td>
% <td>two</td></tr></table>
% </html>
% 
LaTeX Markup
%% LaTeX Markup Example
% <latex>
% \begin{tabular}{|r|r|}
% \hline $n$&$n!$\\ 
% \hline 1&1\\ 2&2\\ 3&6\\ 
% \hline
% \end{tabular}
% </latex>
%

Sections and Section Titles

Code sections allow you to organize, add comments, and execute portions of your code. Code sections begin with double percent signs (%%) followed by an optional section title. The section title displays as a top-level heading (h1 in HTML), using a larger, bold font.

    Note:   You can add comments in the lines immediately following the title. However, if you want an overall document title, you cannot add any MATLAB code before the start of the next section (a line starting with %%).

For instance, the following code produces a polished result when published.

%% Vector Operations
% You can perform a number of binary operations on vectors.
%%
A = 1:3;
B = 4:6;
%% Dot Product
% A dot product of two vectors yields a scalar.  
% MATLAB has a simple command for dot products.
s = dot(A,B);
%% Cross Product
% A cross product of two vectors yields a third
% vector perpendicular to both original vectors.
% Again, MATLAB has a simple command for cross products.
v = cross(A,B);

By saving the code in an Editor and clicking the Publish button on the Publish tab, MATLAB produces the output as shown in the following figure. Notice that MATLAB automatically inserts a Contents menu from the section titles in the MATLAB file.

Text Formatting

You can mark selected strings in the MATLAB comments so that they display in italic, bold, or monospaced text when you publish the file. Simply surround the text with _, *, or | for italic, bold, or monospaced text, respectively.

For instance, the following lines display each of the text formatting syntaxes if published.

%% Calculate and Plot Sine Wave
% _Define_ the *range* for |x|

Trademark Symbols

If the comments in your MATLAB file include trademarked terms, you can include text to produce a trademark symbol (™) or registered trademark symbol (®) in the output.

For example, suppose you enter lines in a file as shown below.

%% Basic Matrix Operations in MATLAB(R)
% This is a demonstration of some aspects of MATLAB(R)
% software and the Neural Network Toolbox(TM) software.

If you publish the file to HTML, it appears in the MATLAB Web browser.

Bulleted and Numbered Lists

MATLAB allows bulleted and numbered lists in the comments. You can use the following syntax to produce bulleted and numbered lists.

%% Two Lists
%
% * ITEM1 
% * ITEM2
%
% # ITEM1
% # ITEM2
%

Publishing the example code produces the following output.

Text and Code Blocks

Preformatted Text

Preformatted text appears in monospace font, maintains white space, and does not wrap long lines. Two spaces must appear between the comment symbol and the text of the first line of the preformatted text.

Publishing the following code produces a preformatted paragraph.

%%
% Many people find monospaced texts easier to read:
%
%  A dot product of two vectors yields a scalar.
%  MATLAB has a simple command for dot products.

Syntax Highlighted Sample Code

Executable code appears with syntax highlighting in published documents. You can also highlight sample code. Sample code is code that appears within comments.

To indicate sample code, you must put three spaces between the comment symbol and the start of the first line of code. For example, clicking the Code button on the Publish tab puts the following code in your Editor.

%%
% Teach your computer to count to ten.
%
%   for i = 1:10
%       disp(x)
%   end
 

Publishing this code to HTML produces output in the MATLAB Web browser.

External Graphics

You can insert text markup to publish an image that the MATLAB code does not generate. By default, MATLAB already includes code-generated graphics.

You can insert a generic image called FILENAME.PNG into your published output:

%%
% 
% <<FILENAME.PNG>>
% 

MATLAB requires FILENAME.PNG be a relative path from the output location to your external image or a fully qualified URL. It is a good practice to save your image in the same folder that MATLAB publishes its output. For example, MATLAB publishes HTML documents to a subfolder html. Save your image file in the same subfolder. You can change the output folder by changing the publish configuration settings.

External Graphics Example Using surf(peaks)

This example shows how to insert surfpeaks.jpg into a MATLAB file for publishing.

To create the surfpeaks.jpg, run the following code in the Command Window.

saveas(surf(peaks),'surfpeaks.jpg');

To produce an HTML file containing surfpeaks.jpg from a MATLAB file:

  1. Create a subfolder called html in your current folder.

  2. Create surfpeaks.jpg by running this code in the Command Window.

    saveas(surf(peaks),'html/surfpeaks.jpg');
  3. Publish this MATLAB code to HTML.

    %% Image Example
    % This is a graphic:
    %
    % <<surfpeaks.jpg>>
    %

Valid Image Types for Output File Formats

The type of images you can include when you publish depends on the output type of that document as indicated in this table. For greatest compatibility, MathWorks® recommends using the default image format for each output type.

Output File FormatDefault Image FormatTypes of Images You Can Include
docpng

Any format that your installed version of Microsoft® Office supports.

htmlpng

All formats publish successfully. Ensure that the tools you use to view and process the output files can display the output format you specify.

latexpng or epsc2

All formats publish successfully. Ensure that the tools you use to view and process the output files can display the output format you specify.

pdfbmp

bmp and jpg.

pptpng

Any format that your installed version of Microsoft Office supports.

xmlpng

All formats publish successfully. Ensure that the tools you use to view and process the output files can display the output format you specify.

Image Snapshot

You can insert code that captures a snapshot of your MATLAB output. This is useful, for example, if you have a for loop that modifies a figure that you want to capture after each iteration.

For example, the following code runs a for loop three times and produces output after every iteration. The snapnow command captures all three images produced by the code.

%% Scale magic Data and Display as Image

for i=1:3
    imagesc(magic(i))
    snapnow;
end

If you publish the file to HTML, it resembles the following figure. By default, the images in the HTML are larger than shown in the figure. To resize images generated by MATLAB code, use the Max image width and Max image height fields in the Publish settings pane, as described in Output Preferences for Publishing.

LaTeX Equations

Inline LaTeX Expression

MATLAB allows you to include an inline LaTeX expression in any code that you intend to publish. To insert an inline expression, surround your LaTeX markup with dollar sign characters ($).

    Note:   All publishing output types support LaTeX expressions, except Microsoft PowerPoint®.

This code contains a LaTeX expression:

%% LaTeX Inline Expression Example
%
% This is an equation: $x^2+e^{\pi i}$. It is 
% inline with the text.

If you publish the sample text markup to HTML, the output appears:

LaTeX Display Equation

MATLAB allows you to insert LaTeX symbols in blocks offset from the main comment text. Two dollar sign characters ($$) on each side of your equation denotes a block LaTeX equation.

This code is a sample text markup.

%% LaTeX Equation Example
%
% This is an equation:
%
% $$e^{\pi i} + 1 = 0$$
%
% It is not in line with the text.

If you publish to HTML, the expression appears as shown here.

Hyperlinks

Static Hyperlinks

You can insert static hyperlinks within a MATLAB comment, and then publish the file to HTML, XML or Microsoft Word. When specifying a static hyperlink to a Web location, you must include a complete URL within the code. This is useful when you want to point the reader to a Web location. You can display or hide the URL in the published text. Consider excluding the URL, when you are confident that readers are viewing your output online and can click the hyperlink.

Enclose URLs and any replacement text in angled brackets.

%%
% For more information, see our Web site:
% <http://www.mathworks.com MathWorks>

Publishing the code to HTML produces the following output.

Eliminating the text MathWorks after the URL produces the following modified output.

    Note:   If your code produces hyperlinked text in the MATLAB Command Window, the output shows the HTML code rather than the hyperlink.

Dynamic Hyperlinks

You can insert dynamic hyperlinks, which MATLAB evaluates at the time a reader clicks that link. Dynamic hyperlinks allow you to point the reader to MATLAB code or documentation, or allow the reader to run code. You implement these links using matlab: syntax. If the code that follows the matlab: declaration has spaces in it, replace them with %20.

    Note:   Dynamic links only work when viewing HTML in the MATLAB Web browser.

Diverse uses of dynamic links include:

Dynamic Link to Run Code.  You can specify a dynamic hyperlink to run code when a user clicks the hyperlink. For example, the following matlab: syntax creates hyperlinks in the output, which when clicked either enable or disable recycling:

%% Recycling Preference
% Click the preference you want:
%
% <matlab:recycle('off') Disable recycling>
%
% <matlab:recycle('on') Enable recycling>

When you publish the file to HTML, the results resemble the following.

When you click one of the hyperlinks, MATLAB sets the recycle command accordingly. After clicking a hyperlink, run recycle in the Command Window to confirm the setting is as you expect.

Dynamic Link to a File.  You can specify a link to a file that you know is in your readers' matlabroot. You do not need to know where each reader installed MATLAB. For example, link to the function code for publish.

%%
% See the 
% <matlab:edit(fullfile(matlabroot,'toolbox','matlab','codetools','publish.m')) code> 
% for the publish function.

Next, publish the file to HTML.

When you click the code link, the MATLAB Editor opens and displays the code for the publish function. On the reader's system, MATLAB issues the command (although the command does not appear in the reader's Command Window).

Dynamic Link to a MATLAB Function Reference Page.  You can specify a link to a MATLAB function reference page using matlab: syntax. For example, suppose your readers have MATLAB installed and running. Provide a link to the publish reference page:

%%
% See the help for the <matlab:doc('publish') publish> function.

Publish the file to HTML.

When you click the publish hyperlink, the MATLAB help browser opens and displays the reference page for the publish function. On the reader's system, MATLAB issues the command, although the command does not appear in their Command Window.

HTML Markup

You can insert HTML markup into your MATLAB file. You must type HTML markup; no button on the Publish tab generates it.

    Note:   When you insert text markup for HTML code, the HTML code publishes only when the specified output file format is HTML.

The following code includes HTML tagging.

%% HTML Markup Example
% This is a table:
%
% <html>
% <table border=1><tr><td>one</td><td>two</td></tr>
% <tr><td>three</td><td>four</td></tr></table>
% </html>
%

If you publish the code to HTML, MATLAB creates a single-row table with two columns. The table contains the values one, two, three, and four.

If a section produces command-window output that starts with <html> and ends with </html>, MATLAB includes the source HTML in the published output. For example, MATLAB displays the disp command and makes a table from the HTML code if you publish this code:

disp('<html><table><tr><td>1</td><td>2</td></tr></table></html>')

LaTeX Markup

You can insert LaTeX markup into your MATLAB file. Any LaTeX markup must be typed; no button on the Publish tab generates it.

    Note:   When you insert text markup for LaTeX code, that code publishes only when the specified output file format is LaTeX.

The following code is an example of LaTeX markup.

%% LaTeX Markup Example
% This is a table:
%
% <latex>
% \begin{tabular}{|c|c|} \hline
% $n$ & $n!$ \\ \hline
% 1 & 1 \\
% 2 & 2 \\
% 3 & 6 \\ \hline
% \end{tabular}
% </latex>

If you publish the file to LaTeX, then the Editor opens a new .tex file containing the LaTeX markup.

% This LaTeX was auto-generated from MATLAB code.
% To make changes, update the MATLAB code and republish this document.

\documentclass{article}
\usepackage{graphicx}
\usepackage{color}

\sloppy
\definecolor{lightgray}{gray}{0.5}
\setlength{\parindent}{0pt}

\begin{document}

    
    

\section*{LaTeX Markup Example}

\begin{par}
This is a table:
\end{par} \vspace{1em}
\begin{par}

\begin{tabular}{|c|c|} \hline
$n$ & $n!$ \\ \hline
1 & 1 \\
2 & 2 \\
3 & 6 \\ \hline
\end{tabular}

\end{par} \vspace{1em}



\end{document}

MATLAB includes any additional markup necessary to compile this file with a LaTeX program.

More About

Was this topic helpful?