When publishing your MATLAB ® code files ( .m ), you can enhance the readability of the published documents by adding markup to the comments within the files. Adding markup allows you to format the published documents and display external files and graphics.
To insert markup, you can:
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:
%% SECTION TITLE % DESCRIPTIVE TEXT
%%% SECTION TITLE WITHOUT SECTION BREAK % DESCRIPTIVE TEXT
% _ITALIC TEXT_
% *BOLD TEXT*
% |MONOSPACED TEXT|
% Trademarks: % TEXT(TM)
% TEXT(R)
%% Bulleted List % % * BULLETED ITEM 1 % * BULLETED ITEM 2 %
%% Numbered List % % # NUMBERED ITEM 1 % # NUMBERED ITEM 2 %
%% % % PREFORMATTED % TEXT %
%% MATLAB(R) Code % % for i = 1:10 % disp x % end %
% %filename.m %
snapnow;
%% Inline Expression % $x^2+e^<\pi i>$
%% Block Equation % % $$e^ <\pi i>+ 1 = 0$$ %
% % %
| one | %two |
%% LaTeX Markup Example %% \begin <|r|r|>% \hline $n$&$n!$\\ % \hline 1&1\\ 2&2\\ 3&6\\ % \hline % \end % %
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, this 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 this figure. Notice that MATLAB automatically inserts a Contents menu from the section titles in the MATLAB file.
You can mark selected text 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, these lines display each of the text formatting syntaxes if published.
%% Calculate and Plot Sine Wave % _Define_ the *range* for |x|
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. Simply add (R) or (TM) directly after the term in question, without any space in between.
For example, suppose that you enter these lines in a file.
%% Basic Matrix Operations in MATLAB(R) % This is a demonstration of some aspects of MATLAB(R) % and the Symbolic Math Toolbox(TM).
If you publish the file to HTML, it appears in the MATLAB web browser.
MATLAB allows bulleted and numbered lists in the comments. You can use this syntax to produce bulleted and numbered lists.
%% Two Lists % % * ITEM1 % * ITEM2 % % # ITEM1 % # ITEM2 %
Publishing the example code produces this output.
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 this code produces a preformatted paragraph.
%% % Many people find monospaced text easier to read: % % A dot product of two vectors yields a scalar. % MATLAB has a simple command for dot products.
Executable code appears with syntax highlighting in published documents. You also can 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 inserts the following sample code in your Editor.
%% % % for i = 1:10 % disp(x) % end %
Publishing this code to HTML produces output in the MATLAB web browser.
To add external file content into MATLAB published code, use the markup. Specify the external file path relative to the location of the published file. Included MATLAB code files publish as syntax-highlighted code. Any other files publish as plain text.
For example, this code inserts the contents of sine_wave.m into your published output:
%% External File Content Example % This example includes the file contents of sine_wave.m into published % output. % %sine_wave.m % % The file content above is properly syntax highlighted.
Publish the file to HTML.
To publish an image that the MATLAB code does not generate, use text markup. By default, MATLAB already includes code-generated graphics.
This code inserts a generic image called FILENAME.PNG into your published output.
MATLAB requires that FILENAME.PNG be a relative path from the output location to your external image or a fully qualified URL. Good practice is 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. In MATLAB Online™ , save your image file to your Published folder, which is located in your root folder.
This example shows how to insert surfpeaks.jpg into a MATLAB file for publishing.
To create the surfpeaks.jpg , run this code in the Command Window.
saveas(surf(peaks),'surfpeaks.jpg');
To produce an HTML file containing surfpeaks.jpg from a MATLAB file:
saveas(surf(peaks),'html/surfpeaks.jpg');
%% Image Example % This is a graphic: % % > %
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, best practice is to use the default image format for each output type.
Any format that your installed version of Microsoft ® Office supports.
All formats publish successfully. Ensure that the tools you use to view and process the output files can display the output format you specify.
All formats publish successfully. Ensure that the tools you use to view and process the output files can display the output format you specify.
Any format that your installed version of Microsoft Office supports.
All formats publish successfully. Ensure that the tools you use to view and process the output files can display the output format you specify.
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.
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 output. 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.
MATLAB enables 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 ( $ ). The $ must immediately precede the first word of the inline expression, and immediately follow the last word of the inline expression, without any space in between.
Note
This code contains a LaTeX expression:
%% LaTeX Inline Expression Example % % This is an expression: $x^2+e^<\pi i>$. It is % inline with the text.
If you publish the sample text markup to HTML, this is the resulting output.
MATLAB enables you to insert LaTeX symbols in blocks that are offset from the main comment text. Two dollar sign characters ( $$ ) on each side of an equation denote a block LaTeX equation. Publishing equations in separate blocks requires a blank line in between blocks.
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 equation appears as shown here.
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, 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: %
Publishing the code to HTML produces this output.
Eliminating the text MathWorks after the URL produces this modified output.
Note
If your code produces hyperlinked text in the MATLAB Command Window, the output shows the HTML code rather than the hyperlink.
You can insert dynamic hyperlinks, which MATLAB evaluates at the time a reader clicks that link. Dynamic hyperlinks enable you to point the reader to MATLAB code or documentation, or enable 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, this matlab: syntax creates hyperlinks in the output, which when clicked either enable or disable recycling:
%% Recycling Preference % Click the preference you want: % % % %The published result resembles this HTML output.
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 that the setting is as you expect.
Dynamic Link to a File. You can specify a link to a file that you know is in the matlabroot of your reader. You do not need to know where each reader installed MATLAB. For example, link to the function code for publish .
%% % See the % % 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 that your reader has MATLAB installed and running. Provide a link to the publish reference page.
%% % See the help for the 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 the Command Window.
You can insert HTML markup into your MATLAB file. You must type the HTML markup since 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.
This code includes HTML tagging.
%% HTML Markup Example % This is a table: % % %
| one | two |
| three | four |
If you publish the code to HTML, MATLAB creates a 2-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 and ends with , 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('1 2
')
You can insert LaTeX markup into your MATLAB file. You must type all LaTeX markup since 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.
This code is an example of LaTeX markup.
%% LaTeX Markup Example % This is a table: % %% \begin <|c|c|>\hline % $n$ & $n!$ \\ \hline % 1 & 1 \\ % 2 & 2 \\ % 3 & 6 \\ \hline % \end %
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 \usepackage \usepackage \sloppy \definecolor \setlength<\parindent> \begin \section* \begin This is a table: \end \vspace \begin \begin <|c|c|>\hline $n$ & $n!$ \\ \hline 1 & 1 \\ 2 & 2 \\ 3 & 6 \\ \hline \end \end \vspace \endMATLAB includes any additional markup necessary to compile this file with a LaTeX program.
