Marking Up MATLAB Comments for Publishing

Note   Many examples in this section show the effects of publishing to HTML. For information on how to publish to HTML, see Specifying Output Preferences for Publishing.

Overview of Marking Up MATLAB Comments for Publishing

This section describes how to mark up comments in your MATLAB files so that when you publish the code, it appears polished, rather than as a text file of code. You can single-source your MATLAB code with documentation that describes what the code is doing.

You can mark up MATLAB comments in either of the following ways to specify the appearance of the file when you publish it:

• Use Cell > Insert Text Markup menu options to format the comments.

  This method automatically inserts the text markup for you.

• Type the markup directly in the comments.

  The markup symbols you type are the same as the text markup that results when you use the equivalent menu item. See Summary of Markup for Publishing MATLAB Files for details.

You can use text markup as you create a file, to mark up an existing file, or a combination of the two. When you use the Cell menu options, the Editor might insert more comment lines and other markup that you want.

Several examples in the sections that follow use this file, sine_wave.m:

% Define the range for x.
% Calculate and plot y = sin(x).
% Display plot in published MATLAB code.
x = 0:1:6*pi;
y = sin(x);
plot(x,y)
title('Sine Wave', 'FontWeight','bold')
xlabel('x')
ylabel('sin(x)')
set(gca, 'Color', 'w')
set(gcf, 'MenuBar', 'none') 

Back to Top

Creating Document Titles and Introductory Text for Publishing an Existing File

To specify a document title and introductory text for a MATLAB file, follow these steps:

1. In the Editor, position the cursor anywhere in the file.

2. Select Cell > Insert Text Markup > Document Title and Introduction. The first three lines of the file appear as shown in the following image.

   

3. Replace DOCUMENT TITLE with the cell heading that you want to use; for example, Plot Sine Wave.

4. Replace INTRODUCTORY TEXT with text that introduces the file; for example, Calculate and plot a sine wave.

5. Insert a blank comment line to increase readability.

If you specify the example text suggested in the previous list, then the resulting file appears as follows.

Notice that a horizontal rule, which indicates a cell break, ends the title and introductory text. When you insert a document title and introduction, the Editor also adds a cell break in preparation for the first section within the file.

When you publish the file, the document title is displays as a top-level heading (h1 in HTML), using a large size, bold font. The introductory text appears polished. The following figure shows the file published to HTML and presented in the MATLAB Web Browser.

Specifying a Title for the New Section that the Editor Inserts with the Document Title

When you follow the steps in the previous section, Creating Document Titles and Introductory Text for Publishing an Existing File, the first cell, demarcated in the Editor with the horizontal rule followed by a line with double percent signs (%%), does not appear when you publish the file. It is not evident because the section does not have a title.

To provide a title for the section, insert text after the double percent signs on line 4—for example, Calculate and Plot Sine Wave. When you republish the file to HTML, it appears in the MATLAB Web Browser as shown in the following image. Notice that MATLAB automatically inserts the Contents heading and the link to the section when you publish the file to HTML.

The file now has a document title, introductory text, and a first section. You can add more sections, as described in Creating New Section Titles.

Note   You can add any comments in the lines immediately following the title. However, if you want the title to appear as the overall document title, you cannot add any other text before the next cell (a line starting with %%) .

Creating New Section Titles

To insert a new section title and descriptive text within a MATLAB file, follow these steps:

1. Position the cursor where you want to insert a new cell—before the title function shown in the example, for instance.

2. Select Cell > Insert Text Markup > Section Title with Cell Break. The file appears as follows.

   

3. Replace SECTION TITLE with your title—Modify Plot Properties, for example.

4. Replace DESCRIPTIVE TEXT with text that describes the cell—Add labels and set colors., for example.

If you specify the example text suggested in the previous list and Specifying a Title for the New Section that the Editor Inserts with the Document Title, then the resulting file appears as follows.

When you publish the file to HTML, the section title appears as a heading, using a medium size, bold font. Comments appear as polished text. The following figure shows the results when you publish the updated sine_wave.m file to HTML output. Notice that the Modify Plot Properties heading is appears as an h2.

Back to Top

Specifying Preformatted Text in MATLAB Files for Publishing

MATLAB software enables you to specify preformatted text in a MATLAB file. Preformatted text appears in monospace font, maintains white space, and does not wrap long lines.

To insert preformatted text, follow these steps:

1. Position the cursor within the file where you want to insert preformatted text.

2. Select Cell > Insert Text Markup > Preformatted Text.

   Five lines of text are inserted.

   

3. Being careful not to delete the two blank spaces before the word PREFORMATTED, replace the words PREFORMATTED and TEXT with your text. Your text can include tabs, spaces, and additional comment lines. For example:

   1. Replace PREFORMATTED with Preformatted text line 1.

   2. Insert a tab before TEXT on line 4.

   The resulting comments appear as follows.

   

If you save the file to preformatted_text.m and then publish the file to HTML, the output appears as shown in the following figure.

Back to Top

Specifying Bulleted or Numbered Lists in MATLAB Files for Publishing

The following steps describe how to specify text markup for a bulleted or numbered list, so that it appears as shown when you publish it. .

1. Position the cursor at the end of the line that precedes the location where you want to add a list. For example, if your file contains the following lines, position the cursor after the colon:

   %%
   % This cell has three items:

2. Select Cell > Insert Text Markup > Bulleted List or Cell > Insert Text Markup > Numbered List, depending on the type of list you want.

   MATLAB adds four lines of comments to the file. The following figure shows the result when you insert a bulleted list.

   

   If you insert a numbered list, the text markup is the same, except a number sign (#) indicates a numbered list item.

3. Replace the sample text, ITEM1 and ITEM2, with your text. For example, replace ITEM1 with A and replace ITEM2 with B.

4. To create a multiline list item, break the line as desired, but do not insert the list item symbol (* or #) before the second line. For example, to insert the alphabet as a multiline list item, breaking the line at the letter p, type the alphabet as shown in the following figure.

   

   Notice that the third list item breaks over two comment lines in the source, yet maintains the appearance of a list when published (as shown at the beginning of this section).

Back to Top

Specifying Graphics in MATLAB Files for Publishing

You can insert text markup to publish an image that the MATLAB code did not generate. This is shown in the following example. (By default, the publishing includes images generated by the MATLAB code.)

1. Position the cursor where you want to add a graphic. For example, if your file contains the following lines, position the cursor after the colon:

   %% Image Example
   % This is a graphic:

2. Select Cell > Insert Text Markup > Image. MATLAB adds text markup, as shown in the following figure.

   

3. Replace FILENAME.PNG, with the file name of the graphic you want to insert, relative to the folder where MATLAB publishes the file.

   For example, if you want to include the graphic, surfpeaks.png, and it is in the folder into which MATLAB publishes the MATLAB code file, then replace FILENAME.PNG with surfpeaks.png. See Creating the surfpeaks.png Image.

   By default, MATLAB publishes the file to an /html subfolder of the folder containing the file. You can change this folder, referred to as the output folder, by changing the publish configuration settings, as described in Specifying Output Preferences for Publishing.

   If the graphic is not in the folder to which you publish the file, then you must specify the location of the graphic file as a relative path from the location of the file that results from publishing. The following table summarizes how to specify such graphics, assuming the folder containing the MATLAB code is I:\my_MATLAB_files.

   Folder Where publish Saves the Output	Image File Location	How to Specify the Image in the MATLAB Comment
   I:/my_MATLAB_files/html	I:/my_MATLAB_files/html	% <<surfpeaks.jpg>>
   I:/my_MATLAB_files/doc	I:/my_MATLAB_files/images	% <<../images/surfpeaks.jpg>>

When you publish the file to HTML, the output appears as shown in the following figure.

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 the table that follows. For greatest compatibility, MathWorks recommends using the default image format for each output type.

Creating the surfpeaks.png Image

To create the surfpeaks.png image used in the preceding example, follow these steps:

1. Create an html subfolder in the folder where the file that references the graphic is located.

2. Enter the following in the Command Window:

   >> surf(peaks)

   A Figure window opens and displays the surfpeaks figure.

3. Save the figure as surfpeaks.jpg in the html subfolder that you created in step 1.

Note   Unless you reduce the size of surfpeaks.jpg, it will appear larger than shown in the previous example.

Back to Top

Using HTML Markup Tags in MATLAB Files for Publishing

You can use the Cell menu to insert HTML code into your MATLAB file. When you do so, the Editor inserts HTML code for a one-column, two-row table. You can use the inserted code as a guideline for inserting other HTML code.

Note   When you insert text markup for HTML code, the HTML code publishes only when the specified output file format is HTML. For example, if you add HTML markup, but then specify LaTeX as the output file format, publishing excludes the text enclosed within the HTML markup. See Specifying Output Preferences for Publishing for information on specifying the output file format.

To insert the text markup for HTML code, follow these steps:

1. Position the cursor at the end of the comment that precedes the location where you want to insert HTML code. For example, if the file contains the following lines, position the cursor after the colon:

   %% HTML Markup Example
   % This is a table:

2. Select Cell > Insert Text Markup > HTML Markup. MATLAB adds HTML markup, as shown in the following figure.

   

3. Edit the inserted HTML code to specify the HTML code that you want to use.

If you publish the file to HTML and leave the inserted HTML code as is, MATLAB creates a single-row table with two columns. The table contains the values one and two, as shown in the following figure.

Back to Top

Using LaTeX Markup for Publishing

Use the Cell menu to insert LaTeX code into your file for publishing. Then, use the inserted code as a guideline for inserting other LaTeX code.

Note   When you insert text markup for LaTeX code, that code publishes only when the specified output file format is LaTeX. For example, if you add LaTeX markup, but specify HTML as the output file format, publishing excludes the code enclosed within the LaTeX markup. See Specifying Output Preferences for Publishing for information on specifying the output file format.

To insert the text markup for LaTeX code, follow these steps:

1. Position the cursor at the end of the comment that precedes the location where you want to insert LaTeX code. For example, if the file contains the following lines, position the cursor after the colon:

   %% LaTeX Markup Example 
   % This is a table:

2. Select Cell > Insert Text Markup > LaTeX Markup. MATLAB adds LaTeX markup, as shown in the following figure.

   

3. Edit the inserted LaTeX code to specify the LaTeX code that you want to use.

Suppose you publish the file to LaTeX, and leave the inserted markup text as is. In that case, the Editor opens a new file with the LaTeX code, as shown in the following figure. (See Creating a Publish Configuration for a MATLAB File for information on specifying LaTeX as the output format.)

If you compile the published LaTeX code, it appears as follows.

Back to Top

Including Inline LaTeX Math Equations in MATLAB Files for Publishing

Use the Cell menu to include an inline LaTeX math equation in MATLAB code that you intend to publish. Then, use the inserted equation as a guideline for inserting other LaTeX math equations.

Note   Publishing supports all output types for LaTeX math equations, except Microsoft PowerPoint®. For PowerPoint output, see Using LaTeX Markup for Publishing.

1. Position the cursor within the line where you want to add an equation. For example, if your file contains the following lines, position the cursor between the colon and the period in the third line:

   %% LaTeX Inline Equation Example
   %
   % This is an equation:. It is in line 
   % with the text.

2. Select Cell > Insert Text Markup > LaTeX Inline Math to insert the markup for the sample equation shown here.

   

3. Replace x^2+e^{\pi i} with the LaTeX math symbols that you want, being careful not to delete the dollar sign characters ($).

   For a list of symbols you can display, and the character sequence to create them, see the MATLAB String property.

If you publish the file to HTML, it appears as shown here. (For this example, the only change to the inserted sample code is the deletion of the space between the inserted markup and the period.)

Back to Top

Including LaTeX Display Math in MATLAB Files for Publishing

Use the Cell menu to insert LaTeX symbols in blocks offset from the main comment text. Then, use the inserted code as a guideline for inserting other LaTeX code. A block of LaTeX symbols is sometimes referred to as display math.

1. Position the cursor before the line where you want to add the display math. For example, if your file contains the following lines, position the cursor after the colon on the end of the third line:

   %% LaTeX Display Math Example
   %
   % This is an equation:
   % It is not in line with the text.

2. Select Cell > Insert Text Markup > LaTeX Display Math to insert the sample equation markup.

   

3. Replace the inserted sample markup e^{\pi i} + 1 = 0 with the LaTeX math symbols that you want to use, being careful not to delete the dollar sign characters ($).

   For a list of symbols that you can display and the character sequence to create them, see the MATLAB String property.

If you leave the inserted sample text markup as is, and publish to HTML, it appears as shown here.

Back to Top

Forcing a Snapshot of Output in MATLAB Files for Publishing

You can use the Cell menu to insert code that forces a snapshot of output, such as a figure. This is useful, for example, if you have a for loop that generates numerous figures and you want to publish them all, after the for loop end statement.

1. Position the cursor at the end of the line where you want to force a snapshot of the output. For example, if your file contains the following lines, position the cursor after the line containing the imagesc function:

   %% Scale magic Data and Display as Image:
   
   for i=1:3
       imagesc(magic(i))  
   end

2. Select Cell > Insert Text Markup > Force Snapshot to insert the snapnow function:

   %% Scale magic Data and Display as Image:
   
   for i=1:3
       imagesc(magic(i))
       snapnow;
   end
   

3. If you publish the file to HTML, it resembles the following figure. The images in your HTML will be larger than shown in the figure. To resize images generated by MATLAB code, use the Max image width and Max image height Publish settings, as described in Specifying Output Preferences for Publishing.

   

Back to Top

Including Bold, Italic, and Monospaced Text in MATLAB Files for Publishing

You can mark selected strings in the MATLAB comments so that they display in bold, italic, or monospaced text when you publish the file. The following sections provide instructions.

Marking Up Existing Comments with Font Formats

To mark up existing comments, follow these steps:

1. Within a comment, select text that you want to be bold, italic, or monospaced.

2. Select Cell > Insert Text Markup, and then select Bold Text, Italic Text, or Monospaced Text.

Inserting New Comments with Font Formats

To insert sample text that you will replace with your new comment text, follow these steps:

1. Select Cell > Insert Text Markup, and then select Bold Text, Italic Text, or Monospaced Text.

2. Replace the inserted text with the text that you want.

When the Editor inserts sample text, the inserted text appears as follows:

Example of Font Formats

Suppose your file appears as follows.

Mark up the comments as follows:

1. Select the word Define, and then select Cell > Insert Text Markup > Bold Text.

2. Select the word range, and then select Cell > Insert Text Markup > Italic Text.

3. Position the cursor after the word for, insert a space, and then select Cell > Insert Text Markup > Monospaced Text.

   The file appears as follows.

   

4. Replace |MONOSPACED TEXT| with |x|.

If you publish the file to HTML, the output appears as shown in the following figure.

Back to Top

Including Trademarks in MATLAB Files for Publishing

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.

• To produce the trademark symbol, enter (TM) in a MATLAB comment.

• To produce the registered trademark symbol, enter (R) in a MATLAB comment.

For example, suppose you enter lines in a file as shown in the following image.

If you publish the file to HTML, it appears as follows in the MATLAB Web Browser.

Back to Top

Including Hyperlinks in MATLAB Files for Publishing

You can insert dynamic or static hyperlinks within a MATLAB comment, and then publish the MATLAB file to HTML or XML. You can also publish static hyperlinked text to Microsoft Word.

When you specify a dynamic hyperlink, MATLAB evaluates the hyperlinked code when someone clicks it in the output. This practice is useful when, for example, you want to point the reader to MATLAB code or documentation or you want the link to run code. When you specify a static hyperlink to a Web location, you specify a complete URL within the code. This is useful when you want to point the reader to a location on the Web. For both static and dynamic hyperlinks, the output contains active hyperlinks.

You can include or exclude the URL from a static hyperlink. Consider including the URL, for example, when you anticipate that readers of your output file might view it in printed form, and therefore need the URL. Consider excluding the URL, when you are confident that readers will view your output online and therefore be able to click the hyperlink.

This section includes the following topics:

• Inserting Static Hyperlinks and Publishing URLs

• Inserting Static Hyperlinks Without Publishing URLs

• Inserting Dynamic Hyperlinks

• Effect of Copying Hyperlinked Text from the MATLAB Command Window

Inserting Static Hyperlinks and Publishing URLs

You can insert a URL, such as www.mathworks.com, that you know at the time you write the file by following these steps:

1. Within a comment, position the cursor where you want to insert the hyperlinked text. For example, suppose you want to specify a link to more information about a topic and you have the following comment within the file:

   %%
   % For more information, see our Web site:

   Position your cursor after the colon (:).

2. Select Cell > Insert Text Markup > Hyperlinked Text.

   The Editor inserts the following:

   <http://www.mathworks.com MathWorks>

3. Replace www.mathworks.com with the URL you want to use.

4. Delete the string, MathWorks.

When you publish the file to HTML, the results resemble the following figure (except the URL in this image is still http://www.mathworks.com).

Inserting Static Hyperlinks Without Publishing URLs

To insert hyperlinked text without a printed URL, follow these steps:

1. Within a comment, position the cursor where you want to insert the hyperlinked text. For example, suppose you want to specify a hyperlink to the MathWorks Web site and you have the following lines within your file:

   %%
   % For more information, see the MathWorks Web site.

   Select the text you want to replace with a hyperlink. For example, select "MathWorks"

2. Select Cell > Insert Text Markup > Hyperlinked Text. The Editor replaces the selected text with the following:

   <http://www.mathworks.com MathWorks>

   If you publish the file to HTML, the results are as shown in the following figure.

   

3. Replace www.mathworks.com with the URL that you want to use.

4. Replace MathWorks with the text that you want to appear as the hyperlinked text.

Inserting Dynamic Hyperlinks

You can insert a hyperlink which MATLAB evaluates at the time a reader clicks that link. You implement these links using matlab: syntax.

You cannot insert dynamic links in Microsoft Word files.

Note   A reader must have MATLAB running for dynamic links to work.

The following sections provide examples:

• Inserting a Dynamic Link To Run Code

• Inserting a Dynamic Link to a File

• Inserting a Dynamic Link to a MATLAB Function Reference Page

Inserting a 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 figure:

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.

Inserting a 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. To insert a dynamic link to a file, follow these steps:

1. Within a comment, position the cursor where you want to insert the link. For example, suppose you want to specify a link to the MATLAB help topic for the publish function. Also suppose you have the following comment within the file:

   %%
   % See the code 
   % for the publish function.
   

2. Replace the word code with the following markup:

   <matlab:web(fullfile(matlabroot,'toolbox','matlab','codetools','publish.m')) code>

   The resulting code now appears as follows:

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

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

When you click the code link, the MATLAB Web browser 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). Notice in the Web browser title bar that the matlabroot specification in the file resolves to the reader's installation folder for MATLAB.

Inserting a 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. To provide a link to the publish reference page, follow these steps:

1. Within a comment, position the cursor where you want to insert the hyperlinked text. For example, suppose you want to specify a link to the MATLAB help topic for the publish function. Furthermore, suppose you have the following comment within the file:

   %%
   % See the help for the publish function.
   

2. Replace the word publish with the following markup:

   <matlab:doc('publish') publish>

   The resulting file code now appears as follows:

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

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

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).

Effect of Copying Hyperlinked Text from the MATLAB Command Window

If you copy statements that display hyperlinked text from the MATLAB Command Window to a file and then publish that file, results might not be as you expect. When you do so, the output shows the code rather than the hyperlink.

For example, suppose you enter the following code in the Command Window:

disp('<a href="http://www.mathworks.com">Link to MathWorks</a>')

When you press Return, the Command Window displays a link to the MathWorks Web site:

However, if you include the preceding disp statement in a file that you publish, the HTML tag and the included text appears in the output, rather than a link:

disp('<a href="http://www.mathworks.com">Link to MathWorks</a>')

Instead, use one of the methods described in these sections:

• Inserting Static Hyperlinks and Publishing URLs

• Inserting Static Hyperlinks Without Publishing URLs

• Inserting Dynamic Hyperlinks

Back to Top

Cleaning Up Text Markup Before Publishing MATLAB Files

When you insert text markup into an existing file using the Cell menu options, sometimes more comment lines than you need are inserted. You can adjust the inserted comments as needed for your purposes. If you delete blank comment lines that the Cell menu options insert there might be unintended consequences, however. See Specifying Preformatted Text in MATLAB Files for Publishing for details.

The following example shows how you can use Cell menu options with an existing file.

Suppose a file currently appears in the Editor as shown in the following image.

If you position the cursor anywhere within the file and select Cell > Insert Text Markup > Document Title and Introduction, the file looks like the following.

The file already contains a comment with introductory text, so you can delete the % INTRODUCTORY TEXT line and the double percent sign (%%) line. When you do so, the code appears as follows.

Back to Top

Summary of Markup for Publishing MATLAB Files

The following table provides a summary of the text markup that you can type into a file to achieve the same results as using the Cell > Insert Text Markup menu options. These tables are useful if you are not using the MATLAB Editor, or if you do not want to use menus to apply markup. For a description of the Cell menu options, see Marking Up MATLAB Comments for Publishing.

Note   The blank comment lines preceding and following some items, such as bulleted lists, are required.

Result in Output	Example of Corresponding File Markup
Document title and introduction	%% DOCUMENT TITLE % INTRODUCTORY TEXT
Section title and description	%% SECTION TITLE % DESCRIPTIVE TEXT
Section title without cell break	%%% SECTION TITLE % DESCRIPTIVE TEXT
Bold text	% *BOLD TEXT*
Italic text	% _ITALIC TEXT_
Monospaced text	% |MONOSPACED TEXT|
Hyperlinked text	% <http://www.mathworks.com MathWorks>
Trademark symbol	% TEXT(TM)
Registered trademark symbol	% TEXT(R)
Code to force a snapshot of the current output	snapnow;
Image	% % <<FILENAME.PNG>> %
Bulleted list	% % * ITEM % * ITEM %
Numbered list	% % # ITEM1 % # ITEM2 %
HTML markup	% % <html> % <table border=1><tr> % <td>one</td> % <td>two</td></tr></table> % </html> %
LaTeX display math	% $$e^{\pi i} + 1 = 0$$
LaTeX inline math	% $x^2+e^{\pi i}$
LaTeX markup	% % <latex> % \begin{tabular}{|r|r} % \hline $n$&$n!$\\ % \\hline 1&1\\ 2&2\\ 3&6\\ % \\hline % \end{tabular} % </latex> %
Preformatted text block	% % This is a block of preformatted text. % The first line of commented text must % begin with two blank spaces. %

Back to Top

Overview of Publishing MATLAB Code

Marking Up MATLAB Code for Publishing

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit