| MATLAB® | |
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. |
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') To specify a document title and introductory text for an M-file, follow these steps:
In the Editor, position the cursor anywhere in an M-file.
Select Cell > Insert Text Markup > Document Title and Introduction. The first three lines of the file appear as shown in the following image.
Replace DOCUMENT TITLE with the cell heading that you want to use; for example, Plot Sine Wave.
Replace INTRODUCTORY TEXT with text that introduces the M-file; for example, Calculate and plot a sine wave.
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.
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 %%) . |
To insert a new section title and descriptive text within an M-file, follow these steps:
Position the cursor where you want to insert a new cell—before the title function shown in the previous example, for instance.
Select Cell > Insert Text Markup > Section Title with Cell Break. The file appears as follows.
Replace SECTION TITLE with your title—Modify Plot Properties, for example.
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.
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:
Position the cursor within the M-file where you want to insert preformatted text.
Select Cell > Insert Text Markup > Preformatted Text. Four lines of text are inserted, as shown.
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:
Replace PREFORMATTED with Text line 1.
Insert a tab before TEXT on line 4.
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.
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
.
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:
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.
Replace the sample text, ITEM1 and ITEM2, with your text. For example, replace ITEM1 with A and replace ITEM2 with B.
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.
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.)
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:
Select Cell > Insert Text Markup > Image. MATLAB adds text markup, as shown in the following figure.
Replace FILENAME.PNG, with the file name of the graphic you want to insert, relative to the directory where MATLAB publishes the M-file.
For example, if you want to include the graphic, surfpeaks.jpg, and it is in the directory into which MATLAB publishes the M-file, then replace FILENAME.PNG with surfpeaks.jpg.
By default, MATLAB publishes the M-file to an /html subdirectory of the directory containing the M-file. You can change this directory, 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 directory 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.
| Directory Containing the M-File | Directory 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.
To create the surfpeaks.jpg image used in the preceding example, follow these steps:
Create an html subdirectory in the directory where the M-file that references the graphic is located.
Enter the following in the Command Window:
>> surf(peaks)
A Figure window opens and displays the surfpeaks figure.
Save the figure as surfpeaks.jpg in the html subdirectory 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. |
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 type 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:
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:
Select Cell > Insert Text Markup > HTML Markup. MATLAB adds HTML markup, as shown in the following figure.
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.
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 type 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:
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:
Select Cell > Insert Text Markup > LaTeX Markup. MATLAB adds LaTeX markup, as shown in the following figure.
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.
You can use the Cell menu to insert TeX equations and symbols. You can use the inserted code as a guideline for inserting other TeX code.
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:
%% TeX Equation Example % % This is an equation:
Select Cell > Insert Text Markup > TeX Equation. Sample markup is added, as shown in the following figure.
Replace the inserted sample markup e^{\pi i} + 1 = 0 with the TeX equation 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.
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.
Position the cursor at the end of 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))
endSelect Cell > Insert Text Markup > Force Snapshot. The snapnow function is inserted:
%% Scale magic Data and Display as Image:
for i=1:3
imagesc(magic(i))
snapnow;
end
If you publish the file to HTML, the published document resembles to 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.
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.
To mark up existing comments, follow these steps:
Within a comment, select text that you want to be bold, italic, or monospaced.
Select Cell > Insert Text Markup, and then select Bold Text, Italic Text, or Monospaced Text.
To insert sample text that you will replace with your new comment text, follow these steps:
Select Cell > Insert Text Markup, and then select Bold Text, Italic Text, or Monospaced Text.
Replace the inserted text with the text that you want formatted.
When the Editor inserts sample text, the inserted text appears as follows:
| % *BOLD TEXT* |
| % _ITALIC TEXT_ |
| % |MONOSPACED TEXT| |
Suppose your M-file appears as follows.
Format the comments as follows:
Select the word Define, and then select Cell > Insert Text Markup > Bold Text.
Select the word range, and then select Cell > Insert Text Markup > Italic Text.
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.
Replace |MONOSPACED TEXT| with |x|.
If you publish the M-file to HTML, the output appears as shown in the following figure.
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.
You can insert hyperlinked text within an M-file comment, and then publish the M-file to HTML, XML, or Microsoft® Word. The published document contains active links to URLs on the Web.
You can include or exclude the URL from the hyperlinked text. You might, for example, include the URL when you anticipate that users 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 users will view your published document online and therefore be able to use the text as a link.
To insert a URL as hyperlinked text, follow these steps:
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 (:).
Select Cell > Insert Text Markup > Hyperlinked Text. The Editor inserts the following:
<http://www.mathworks.com The MathWorks>
Replace www.mathworks.com with the URL you want to use.
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).
To insert hyperlinked text without a printed URL, follow these steps:
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.
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.
Replace www.mathworks.com with the URL that you want to use.
Replace MathWorks with the text that you want to appear as the hyperlinked text.
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:
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:
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
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 by copying and pasting the following comments into an M-file in the Editor:
%% Formatted Block Demonstration
% This M-file shows the difference between blocks
% that are and are not formatted.
%
%% Block That Is Formatted
% This first block begins on line 6 of the M-file code.
% Because there are two spaces between the percent sign
% and the next character on line 6, this block is
% formatted.
% Here is a list:
% * Item one
% * Item two
%
%% Block That Is Not Formatted
% This second block begins on line 15 of the M-file code.
% Because there is only one space between the percent sign
% and the next character on line 15, this block
% is NOT formatted.
% Here is a list:
% * Item one
% * Item two
%
%% Text That Contains Formatted and Unformatted Blocks
% This third block begins on line 24 of the M-file code.
% Because there are two spaces between the percent sign
% and the next character on line 24, this block is
% formatted. Note that the 25th and subsequent lines
% in this block do not have two spaces between the single
% percent sign and the next character on the line. The first
% line within the block determines whether or not the
% entire block is formatted.
%
% This fourth block begins on line 33 of the M-file code.
% It is not a continuation of the third block because a
% blank comment line precedes line 33.
% Even though a tab exists on this line in the
% M-file code, its spacing is not preserved in the
% published document; the tab occurs in the middle
% of a block that is not formatted.
%
%% Indented Text
% This fifth block begins on line 42 of the M-file
% code. It is formatted because there are two
% spaces between the percent sign and the first
% character on line 42. Indenting a line has
% no effect on preformatting and is not presented
% in the published document as indented.
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.
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.
This table summarizes markup that does not require that it be included within a formatted block.
| Result in Published Document | Example of Corresponding M-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 |
| Cell break without title or description | %% |
| 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; |
This table summarizes markup that requires that it be included within a formatted block. See About Formatted Blocks for details.
| Result in Published Document | Example of Corresponding M-File Markup |
|---|---|
| Image | % <<FILENAME.PNG>> % |
| Bulleted list | % * ITEM1 % * ITEM2 |
| Numbered list | % # ITEM1 % # ITEM2 |
| HTML markup | % <html> % <table border=1><tr> % <td>one</td> % <td>two</td></tr></table> % </html> |
| LaTeX markup | % <latex>
% \begin{tabular}{|r|r}
% \hline $n$&$n!$\\
% \\hline 1&1\\ 2&2\\ 3&6\\
% \\hline
% \end{tabular}
% </latex> |
| TeX equation | % $$e^{\pi i} + 1 = 0$$
|
| Overview of Publishing M-Files | Formatting M-File Code for Publishing | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |