Formatting M-File 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 Producing Published Output from M-Files.

Overview of Formatting M-File Comments for Publishing

This section describes the types of text formatting you can specify for M-files, so that your published output appears like a polished document, rather than a text file of code. This enables you to single-source your M-file code with documentation that describes what the code is doing.

You can format M-file comments in either of the following ways to specify how the published results will appear:

• Use Cell > Insert Text Markup menu options to format the comments. This automatically inserts the text markup symbols for you.

• Type the markup symbols directly in the comments; the markup symbols you enter are the same as the text markup that results when you use the equivalent menu item. See Summary of Markup for Formatting M-Files for Publishing for details.

You can use text markup as you create a new file, to mark up an existing M-file, or a combination of the two. When you use the Cell menu options, the Editor may insert more comment lines and other markup that you want. See Cleaning Up Text Markup Before Publishing M-Files for information on how you can adjust the inserted text when you are done formatting a file.

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

% Define the range for x.
% Calculate and plot y = sin(x).
% Display plot in published document.
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 M-File

To specify a document title and introductory text for an M-file, follow these steps:

1. In the Editor, position the cursor anywhere in an M-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 M-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 first four lines of the resulting M-file appear 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 M-file.

When you publish the M-file, the document title is formatted as a top-level heading (h1 in HTML), using a large size, bold font; the introductory text appears as formatted text. The following figure shows the M-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 M-File, the first cell, demarcated in the Editor with the horizontal rule followed by a line with double percent signs (%%), is not evident in the published file because the section does not have a title.

To provide a title for the section, insert text after the double percent signs—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 an M-file, follow these steps:

1. Position the cursor where you want to insert a new cell—before the title function shown in the previous 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 M-file appears as follows.

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

Back to Top

Specifying Preformatted Text in M-Files for Publishing

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

To insert preformatted text, follow these steps:

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

2. Select Cell > Insert Text Markup > Preformatted Text. Five lines of text are inserted, as shown.

   

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

   1. Replace PREFORMATTED with Text line 1.

   2. Insert a tab before TEXT on line 4.

   3. On the last comment line type Text line 3.

   The resulting comments appear as follows.

   

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

If the results are not as you expect, see About Formatted Blocks.

Back to Top

Specifying Bulleted or Numbered Lists in M-Files for Publishing

The following steps describe how to specify text markup for a bulleted or numbered list so as to create a published document that appears as shown in the following image when you click the Publish button .

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 M-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 formatted comments to the M-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 is broken over two comment lines in the source, yet maintains the formatting of a list, as expected, when published (as shown at the beginning of this section).

If the results are not as you expect, see About Formatted Blocks.

Back to Top

Specifying Graphics in M-Files for Publishing

You can insert text markup such that the published document includes an image that was not generated by the M-file code, as shown in the following example. (By default, images generated by the M-file code are included in the published document.)

1. Position the cursor where you want to add a graphic. For example, if your M-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 M-file.

   For example, if you want to include the graphic, surfpeaks.jpg, and it is in the folder into which MATLAB publishes the M-file, then replace FILENAME.PNG with surfpeaks.jpg.

   By default, MATLAB publishes the M-file to an /html subfolder of the folder containing the M-file. You can change this folder, referred to as the output folder, by changing the publish configuration settings, as described in Producing Published Output from M-Files.

   If the graphic is not in the folder to which the M-file is published, then you must specify the location of the graphic file as a relative path from the location of the published output file, as illustrated in the following table.

   Folder Containing the M-File	Folder Where MATLAB Publishes the M-File	Image File Location	How to Specify the Image in the M-File Comment
   I:/my_mfiles	I:/my_mfiles/html	I:/my_mfiles/html	% <<surfpeaks.jpg>>
   I:/my_mfiles	I:/my_mfiles/doc	I:/my_mfiles/images	% <<../images/surfpeaks.jpg>>

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

If the results are not as you expect, see About Formatted Blocks.

Creating the surfpeaks.jpg Image

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

1. Create an html subfolder in the folder where the M-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 that shown in the previous example.

Back to Top

Using HTML Markup Tags in M-Files for Publishing

You can use the Cell menu to insert HTML code into your M-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 is published 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, MATLAB software does not publish the text enclosed within the HTML markup. See Producing Published Output from M-Files 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 M-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 M-file to HTML and leave the inserted HTML code as is, MATLAB creates a single-row table with two columns, containing the values one and two as shown in the following figure.

If the results are not as you expect, see About Formatted Blocks.

Back to Top

Using LaTeX Markup for Publishing

You can use the Cell menu to insert LaTeX code. You can use the inserted code as a guideline for inserting other LaTeX code.

Note   When you insert text markup for LaTeX code, that code is published only when the specified output file format is LaTeX. For example, if you add LaTeX markup, but then specify HTML as the output file format, MATLAB software does not publish the code enclosed within the LaTeX markup. See Producing Published Output from M-Files 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 M-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.

If you publish the M-file to LaTeX, and leave the inserted markup text as is, the Editor opens a new file with the LaTeX code, as shown in the following figure. (See Creating a Publish Configuration for an M-File for information on specifying LaTeX as the output format for a published document.)

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

If the results are not as you expect, see About Formatted Blocks.

Back to Top

Including Inline LaTeX Math Symbols in M-Files for Publishing

You can make LaTeX math symbols appear inline when you publish an M-file to any format, except Microsoft PowerPoint^®. For Microsoft PowerPoint output, consider using an Using LaTeX Markup for Publishing instead.

To make a LaTeX math symbol appear inline, enclose the string within dollar sign symbols ($) within a formatted comment block.

For example, suppose your M-file appears as follows:

When you publish the file to HTML, it appears as in the image that follows. Notice that the LaTeX math symbols are inline with the rest of the text:

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

Back to Top

Including Blocks of LaTeX Math Symbols in M-Files for Publishing

You can use the Cell menu to insert LaTeX symbols in blocks offset from the main comment text. You can use the inserted code as a guideline for inserting other LaTeX code.

1. Position the cursor before the line where you want to add an equation or symbols. For example, if your M-file contains the following lines, position the cursor after the colon on the end of the third line:

   %% LaTeX Block Example
   %
   % This is an equation:
   % It is not inline with the text.

2. Select Cell > Insert Text Markup > TeX Equation 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.

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

If you publish the file to HTML, and leave the inserted sample text markup as is, the published document appears as shown in the following figure.

If the results are not as you expect, see About Formatted Blocks.

Back to Top

Forcing a Snapshot of Output in M-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 include them all in the published output, 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 M-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, the published document resembles the following figure. The images in your published document will be larger than shown in the figure. To resize of images generated by M-file code, you use the Max image width and Max image height Publish settings, as described in Producing Published Output from M-Files.

   

Back to Top

Including Bold, Italic, and Monospaced Text Formats in M-Files for Publishing

You can mark up selected strings in the M-file comments so that they appear in bold, italic, or monospaced text formats when you publish the M-file, as described in the following sections.

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

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

Example of Font Formats

Suppose your M-file appears as follows.

Format 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 M-file appears as follows.

   

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

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

Back to Top

Including Trademarks in M-Files for Publishing

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

• To produce the trademark symbol, enter (TM) in an M-file comment.

• To produce the registered trademark symbol, enter (R) in an M-file comment.

For example, suppose you enter lines in an M-file as shown in the following image.

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

Back to Top

Including Links in M-Files for Publishing

You can insert dynamic or static links within an M-file comment, and then publish the M-file to HTML, or XML. You can also publish static hyperlinked text to Microsoft Word.

When you specify a dynamic link, MATLAB resolves the URL when the user clicks the link in the published document. You do not specify the exact URL in the code. This is useful when, for example, you want to point the reader to some MATLAB code or documentation. When you specify a static link, you specify the complete URL within the M-file code. This is useful when you want to point the user to a location on the Web. For both static and dynamic links, the publish document contains active links.

You can include or exclude the URL from a published static link. You might, for example, include the URL when you anticipate that readers of your published document might view it in printed format, and therefore need the URL. You might exclude the URL, when you are confident that readers will view your published document online and therefore be able to click the link.

This section includes the following topics:

• Inserting Static Links and Publishing URLs

• Inserting Static Links Without Publishing URLs

• Inserting Dynamic Links

• Effect of Using Hyperlinked Text from the MATLAB Command Window

Inserting Static Links and Publishing URLs

You can insert a URL that you know at the time the M-file is written, such as www.mathworks.com, 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. You might have the following comment within the M-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 The MathWorks>

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

4. Delete the string, The MathWorks.

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

Inserting Static Links 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 link to the MathWorks Web site. You might have the following lines within your M-file:

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

   Select the text you want to replace with a link. For example, select "MathWorks," as shown in the following figure.

   

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 M-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 Links

You can insert a link which MATLAB evaluates at the time a reader clicks that link in the published document. You implement these links as matlab: links. Unlike other uses of matlab:, you do not need to use it within another function, such as disp.

You cannot insert dynamic links in Microsoft Word files.

Note   A reader of your published document must have MATLAB running for dynamic links to work.

For more information, see matlabcolon. The following sections provide two examples:

• Inserting a Dynamic Link to a File

• Inserting a Dynamic Link to a MATLAB Function Reference Page

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 M-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 M-file 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 the reader of the published document clicks 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 M-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. For example, suppose you know the readers of your published document 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 M-file:

   %%
   % See the help for the publish function.
   

2. Replace the word publish with the following markup:

   <matlab:doc('publish') publish>

   The resulting M-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 the reader of the published document clicks the publish link, 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 Using Hyperlinked Text from the MATLAB Command Window

You cannot use statements that display hyperlinked text in the MATLAB Command Window to create hyperlinked text in a published M-file. If you try, the published document 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 an M-file that you publish, the HTML tag and the included text appear in the published document, 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 Links and Publishing URLs

• Inserting Static Links Without Publishing URLs

• Inserting Dynamic Links

Back to Top

About Formatted Blocks

Multiple contiguous lines of comments immediately following a cell break are referred to as "descriptive" or "introductory text". Within these lines of comments, empty lines create formatted blocks. Formatted blocks control how comments appear within the final published document.

Specify each of the following items as a formatted block to achieve the intended results in the published document:

• Preformatted text

• Bulleted and numbered lists

• Graphics

• HTML markup

• LaTeX markup

• TeX equations

The following sections provide general information on formatted blocks:

• Understanding How Formatted Blocks are Demarcated

• Understanding How Formatted Blocks Work

Understanding How Formatted Blocks are Demarcated

A formatted block starts on the first comment line after one of the following:

• A cell break

• A blank comment line (a percent sign with no other characters on the line)

A formatted block ends on the last comment line before one of the following:

• A cell break

• A blank comment line

• Any line of uncommented M-file code

Understanding How Formatted Blocks Work

A comment is part of a formatted block if, on the first line of the block there are two spaces between the single percent sign (%) and the next character. Any number of white spaces can precede the percent sign. That is, the percent sign can be indented. The following two images demonstrate the difference between blocks that are and are not formatted:

• The first image show the M-file source code.

• The second image shows the M-file published to an HTML document.

If you want, you can experiment with the code presented in the previous images. Open formatted_block_demo.m by running the following command:

edit(fullfile(matlabroot,'help','techdoc',...
'matlab_env','examples','formatted_block_demo.m'))

To work with formatted_block_demo.m on your system, save the file to a folder for which you have write permission. In the example, the file is saved to I:\my_matlab_files\my_mfiles\formatted_comments.m.

Back to Top

Cleaning Up Text Markup Before Publishing M-Files

When you insert text markup into an existing M-file using the Cell menu options, you might find that 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 may be unintended consequences, however. See Specifying Preformatted Text in M-Files for Publishing for details.

The following example shows how you might use Cell menu options with an existing M-file.

Suppose an M-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 M-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, so the code appears as follows.

Back to Top

Summary of Markup for Formatting M-Files for Publishing

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

Summary of Markup Not Requiring a Formatted Block

This table summarizes markup that does not require that it be included within a formatted block.

%% DOCUMENT TITLE
% INTRODUCTORY TEXT

%% SECTION TITLE
% DESCRIPTIVE TEXT

%%% SECTION TITLE
% DESCRIPTIVE TEXT

%%

% *BOLD TEXT*

% _ITALIC TEXT_

% |MONOSPACED TEXT|

% TEXT(TM)

% TEXT(R)

Summary of Markup Requiring a Formatted Block

This table summarizes markup that requires that it be included within a formatted block. See About Formatted Blocks for details.

% <<FILENAME.PNG>> % 

% * ITEM1
% * ITEM2

% # ITEM1
% # ITEM2

% <html>
% <table border=1><tr>
% <td>one</td>
% <td>two</td></tr></table>
% </html>

% <latex>
% \begin{tabular}{|r|r}
% \hline $n$&$n!$\\ 
% \\hline 1&1\\ 2&2\\ 3&6\\ 
% \\hline
% \end{tabular}
% </latex>

% $$e^{\pi i} + 1 = 0$$

Back to Top

Overview of Publishing M-Files

Formatting M-File 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