Overview of Publishing M-Files :: Publishing M-Files (MATLAB®)

MATLAB^®

Formatting M-File Comments for Publishing

Overview of Publishing M-Files

On this page…
What Is Meant by Publishing M-Files? Using Cells Process for Publishing M-Files Example of a Published M-File Producing the Formatting for the Example

On this page…

What Is Meant by Publishing M-Files?

Using Cells

Process for Publishing M-Files

Example of a Published M-File

Producing the Formatting for the Example

What Is Meant by Publishing M-Files?

The MATLAB^® product allows you to quickly publish your M-file code in a variety of formats, including HTML, XML, and LaTeX. If Microsoft^® Word or Microsoft^® PowerPoint^® applications are on your Microsoft Windows^® system, you can publish to their formats as well. This is useful for creating a report for describing or sharing your M-file code with others who may or may not have MATLAB. You can include the following within the published M-file:

M-file code
Results of running the code, including output to the Command Window and figures created or modified by the code
Formatted commentary on the code, including bulleted and numbered lists, bold and monospace font, preformatted text, TeX equations, and so on

If you have an active Internet connection, you can watch the Publishing M Code from the Editor video demo for an overview of the major publishing features using cells with text markup.

Using Cells

After you write and debug an M-file and are ready to share it with others, you can insert cells and commentary using text markup features available in MATLAB. This enables you to publish a formatted M-file. A cell is a section of M-file code (see What Are Cells?). For the purposes of publishing, a cell can be a section of the code that you want to present as a titled subsection within the published document, or a portion of code for which you want the results of code evaluation to display as it occurs (for example, each iteration of a for loop), or both.

Any cell features that you use for evaluating and improving your code, as described in Using Cells for Rapid Code Iteration and Publishing Results, you also can use for publishing purposes. However, to have formatted comments in the output document, those comments must appear at the start of a cell, before any executable code. This requirement might mean that you need to change cells that you inserted for rapid code iteration. If you do so, be aware that this changes the cells for evaluation purposes, as well.

Example of a Published M-File shows how the cells and formatted comments appear when an M-file is published.

Although you typically include the text markup after you write and debug the code, you can also include text markup as you write the code, or a combination of the two.

Process for Publishing M-Files

The overall process to publish an M-file using cell features in the Editor is as follows:

Open your M-file in the Editor.
Select Cell > Insert Text Markup as described in Formatting M-File Comments for Publishing.
This enables you to specify how M-file comments appear in the published document. For example, you can specify that comments appear as bold or monospaced text in the published document.
To publish the M-file, do one of the following, as described in Producing Published Output from M-Files:
- To publish the M-file with default publishing properties, select File > Publish file name. When you use this method, MATLAB publishes the M-file to HTML in an /html subdirectory of the directory that contains the M-file you are publishing. However, if you previously specified custom property values, as described in the next list item, the last configuration you specified is used and the output type and directory may be different.
- To specify custom publishing properties, select File > Publish Configuration for file name > Edit Publish Configurations for file name, adjust properties, and then click Publish. You can, for example, choose to include or exclude the executable code from the published document.

Example of a Published M-File

This section provides an example to demonstrate how an M-file appears when published. It shows how the M-file appears before and after text markup is added to cells to achieve the formatted results. This section contains the following topics:

For detailed information on inserting text markup, see Formatting M-File Comments for Publishing.

Sample M-File Before Formatting

function fourier_demo
    t = 0:.1:pi*4;
    y = sin(t);
    updatePlot(t,y);
    
    % In each iteration of the for loop add an odd 
    % harmonic to y. As "k" increases, the output 
    % approximates a square wave with increasing accuracy.

    for k = 3:2:9
        % Perform the following mathematical operation
        % at each iteration:
        y = y + sin(k*t)/k;
        
        display(sprintf('When k = %.1f',k));
        display('Then the plot is:');
        updatePlot (t,y)
    end
    
end

% Even though the approximations are constantly  
% improving, they will never be exact because of the 
% Gibbs phenomenon, or ringing.

function updatePlot(t,x)
% Subfunction to update the plot
    cla
    plot(t,x) 
end

Published Sample M-File Before Formatting

Before you add text markup and cell breaks, publishing fourier_demo.m includes the last plot generated by the for loop, but otherwise, has little effect. For example, if you select File > Publish fourier_demo.m, the published results, as shown in the following figure, are of limited use.

Published Sample M-File After Formatting

If you add a few comments for clarity, apply text markup, and insert cell breaks, as described in Producing the Formatting for the Example, the published M-file is transformed as shown in the following three figures:

The first figure shows the top of the published document.
The second figure shows the middle of the published document.
The third figure shows the bottom of the document.

First image of file published with text markup, highlighting key features. The resulting HTML file includes a title, a table of contents, and a smaller size plot.

Second image of file published with text markup, highlighting key features. The resulting HTML file includes text in italic, an equation in TeX format, and a smaller size plot.

Third image of file published with text markup, highlighting key features. The resulting HTML file includes the final plot and a section with a note about the Gibbs phenomenon.

Producing the Formatting for the Example

The following steps apply text markup to the fourier.m file. (The unformatted file appears in Published Sample M-File Before Formatting.) When published to HTML, the results appear as shown in Published Sample M-File After Formatting.

For detailed information about each Cell menu option, see Formatting M-File Comments for Publishing.

Open a new M-file in the Editor, and then enter the fourier_demo.m code shown in Sample M-File Before Formatting into the file.
Enable cell mode by selecting Cell > Enable Cell Mode.
Add an overall title and introduction for the published document:
1. Select Cell > Insert Text Markup > Document Title and Introduction. MATLAB adds the following at the top of the file:
```
%% DOCUMENT TITLE
% INTRODUCTORY TEXT
```
  The double percent signs (%%) indicate the start of a new cell. A single percent sign indicates the beginning of a comment line.
2. Replace DOCUMENT TITLE with Square Waves from Sine Waves.
3. Replace % INTRODUCTORY TEXT with one or more comments about the overall file, for example:
```
% The Fourier series expansion for a square-wave is
% made up of a sum of odd harmonics, as shown here
% using MATLAB(R).
```
  The string "(R)" will appear as a registered trademark symbol in the published document.
4. On line 5, insert a blank line for better readability. Notice that the file now contains two cells. The first cell extends from line 6 to the top of the file; the second cells extends from line 6 to the bottom of the file. The cell break at line 6, splits the file into two cells.
On line 6, where the second cell begins (as indicated by %%), type a title for the cell: Add an Odd Harmonic and Plot It.
Notice that when you move from one cell to the next in the file, the highlighting in the M-file indicates which cell the cursor is currently in.
To display the text that describes the purpose of the loop in the published document as explanatory text, rather than M-file code, insert a cell break before the explanation. That is:
1. Place the cursor at line 12.
2. Select Cell > Insert Cell Divider.
Note that the cell that begins on line 12, continues to the end of the fourier_demo function. If you insert a cell break anywhere within the code block, MATLAB inserts an implicit cell break at the end of a code block. A code block is the body of any programming control statement or function.
Remove the quotation marks around the k at line 14 and present it in italic instead:
1. Delete the quotation marks.
2. Select the letter k.
3. Select Cell > Insert Text Markup > Italic Text.
  Instead of being enclosed in quotation marks, the letter now appears as _k_.
4. To see the effect, click Publish .
Because MATLAB publishes output generated by code immediately after the end of the cell that contains the code, the current cell would cause MATLAB to include the phrase When k = n Then the plot is: four times in succession in the published document. In addition, only the final plot generated by the for loop would be in the published document.
To have MATLAB include every plot generated by the for loop in the published document, each preceded by the phrase When k = n ..., create a cell within the for loop, as follows:
1. Place the cursor at the end of line 17, after for k = 3:2:9.
2. Select Cell > Insert Cell Divider.
  Now the current cell includes only the body of the for loop.
3. To see the effect, click Publish .
Display equations with symbols and Greek characters (such as pi) using the TeX format. In this example, to create a comment containing a nicely formatted form of the equation, y = y + sin(k*t)/k, in the published document, use text markup as follows:
1. Position the cursor at the end of the comment on line 20, % at each iteration.
2. Select Cell > Insert Text Markup > TeX Equation.
  MATLAB inserts the following lines; the second line is a sample equation with text markup applied:
```
% 
% $$e^{\pi i} + 1 = 0$$
%
```
  The sample equation, which is the text between the set of two dollar signs ($$), is highlighted.
3. Replace the sample equation with the following TeX equation:
```
y = y + \frac{sin(k*t)}{k}
```
  The three lines that display the TeX equation now appear as follows in the M-file:
```
%
%  % $$y = y + \frac{sin(k*t)}{k} $$
%
```
4. To see the effect, click Publish .
Reduce the size of the published figures by editing the publish configuration for the file:
1. Select File > Publish Configuration for fourier_demo > Edit Publish Configurations for fourier_demo.m.
  The Edit M-File Configurations dialog box opens.
2. In the column to the right of Max image width (pixels), double-click Inf, and type the value 350.
3. In the column to the right of Max image height (pixels), double-click Inf, and type the value 350.
4. Click Save As. The Save Publish Settings dialog box opens.
5. In the Settings name field, type small_images, and then click Save.
6. Click Close.
7. To see the effect, click Publish .
To create a section header without including a cell break, follow these steps:
1. Position the cursor at the beginning of line 33, where the comment % Even though the approximations are constantly appears.
2. Select Cell > Insert Text Markup > Section Title without Cell Break.
3. Replace SECTION TITLE with Note About Gibbs Phenomenon.
4. Delete line 34, where the comment % DESCRIPTIVE TEXT appears.
Select File > Publish fourier_demo.
The published document, an HTML file, appears in the MATLAB Web Browser, as shown in Published Sample M-File After Formatting.

By default, MATLAB stores the HTML document, fourier_demo.html, and the associated image files in an /html subdirectory within the directory containing the source M-file.

See M-File Code After Text Markup for the resulting M-file code.

M-File Code After Text Markup

After adding text markup, the fourier_demo.m M-file appears as follows. When you publish the file to HTML, it appears as shown in Published Sample M-File After Formatting.

%% Square Waves from Sine Waves
% The Fourier series expansion for a square-wave is
% made up of a sum of odd harmonics, as shown here
% using MATLAB(R). 

%% Add an Odd Harmonic and Plot It
function fourier_demo
    t = 0:.1:pi*4;
    y = sin(t);
    updatePlot(t,y);
    
    %%
    % In each iteration of the for loop add an odd 
    % harmonic to y. As _k_ increases, the output 
    % approximates a square wave with increasing accuracy.

    for k = 3:2:9 
        %%
        % Perform the following mathematical operation
        % at each iteration:
        % 
        % $$ y = y + \frac{sin(k*t)}{k} $$
        % 
        y = y + sin(k*t)/k;
        
        display(sprintf('When k = %.1f',k));
        display('Then the plot is:');
        updatePlot (t,y)
    end
    
end

%%% Note About Gibbs Phenomenon
% Even though the approximations are constantly  
% improving, they will never be exact because of the 
% Gibbs phenomenon, or ringing.

function updatePlot(t,x)
% Subfunction to update the plot
    cla
    plot(t,x) 
end

Publishing M-Files

Formatting M-File Comments for Publishing