发布标记

当发布您的 MATLAB® 代码文件 (.m) 时，您可以通过向文件中的注释添加标记来增强已发布文档的可读性。通过添加标记，您可以对发布的文档进行格式设置并显示外部文件和图形。

标记概述

要插入标记，您可以：

  • 使用发布选项卡上的格式设置按钮和下拉菜单设置文件格式。此方法可自动为您插入文本标记。

  • 从右键点击菜单的插入文本标记列表中选择标记。

  • 直接在注释中键入标记。

下表提供文本标记选项的摘要说明。如果您未使用 MATLAB 编辑器，或者不希望使用发布选项卡应用标记，可参考此表。

注意

处理标记时：

  • 注释符号 (%) 后面的空格通常确定随后的文本的格式。

  • 开始新标记通常需要前面的空注释行，如示例中所示。

  • 标记仅在紧跟有分节符的注释中有效。

输出结果对应文件标记的示例
节和节标题 
%% SECTION TITLE
% DESCRIPTIVE TEXT

%%% SECTION TITLE WITHOUT SECTION BREAK
% DESCRIPTIVE TEXT
文本格式设置 
% _ITALIC TEXT_
% *BOLD TEXT*
% |MONOSPACED TEXT|
% Trademarks:
% TEXT(TM)
% TEXT(R)
项目符号和编号列表 
%% Bulleted List
%
% * BULLETED ITEM 1
% * BULLETED ITEM 2
%
%% Numbered List
%
% # NUMBERED ITEM 1
% # NUMBERED ITEM 2
%
文本和代码块 
%% 
% 
%  PREFORMATTED
%  TEXT
% 

%% MATLAB(R) Code
% 
%   for i = 1:10
%       disp x
%   end
%
外部文件内容 
% 
% <include>filename.m</include>
%
外部图形 
% 
% <<FILENAME.PNG>>
%
图像快照 
snapnow;
LaTeX 方程 
%% Inline Expression
% $x^2+e^{\pi i}$

%% Block Equation
%
% $$e^{\pi i} + 1 = 0$$
%
超链接 
% <https://www.mathworks.com MathWorks> 
% <matlab:FUNCTION DISPLAYED_TEXT>
HTML 标记 
%
% <html>
% <table border=1><tr>
% <td>one</td>
% <td>two</td></tr></table>
% </html>
%
LaTeX 标记 
%% LaTeX Markup Example
% <latex>
% \begin{tabular}{|r|r|}
% \hline $n$&$n!$\\ 
% \hline 1&1\\ 2&2\\ 3&6\\ 
% \hline
% \end{tabular}
% </latex>
%

节和节标题

通过代码节可以整理、添加注释以及执行部分代码。代码节以双百分号 (%%) 开头，后可跟节标题。节标题使用较大的加粗字体显示为顶层标题（HTML 中为 h1）。

注意

您可以在紧随标题后的行中添加注释。但是，如果您需要整体文档的标题，则不能在下一节开头（以 %% 开头的一行）之前添加任何 MATLAB 代码。

例如，此代码在发布时生成美观的结果。

%% Vector Operations
% You can perform a number of binary operations on vectors.
%%
A = 1:3;
B = 4:6;
%% Dot Product
% A dot product of two vectors yields a scalar.  
% MATLAB has a simple command for dot products.
s = dot(A,B);
%% Cross Product
% A cross product of two vectors yields a third
% vector perpendicular to both original vectors.
% Again, MATLAB has a simple command for cross products.
v = cross(A,B);

通过在编辑器中保存代码并点击发布选项卡上的发布按钮，MATLAB 可生成此图窗所示的输出。请注意，MATLAB 可从 MATLAB 文件中的节标题自动插入“内容”菜单。

Published document with the formatted title Vector Operations, a Contents menu, and formatted subheadings for the remaining sections

文本格式设置

您可以标记 MATLAB 注释中的选定文本，以便在您发布文件时使其显示为斜体、粗体或等宽文本。只需用 _、* 或 | 括起文本即可使其分别显示为斜体、粗体或等宽文本。

例如，以下行在发布后显示每个文本格式设置语法。

%% Calculate and Plot Sine Wave
% _Define_ the *range* for |x|

Published document with a line of text that has the word define in italics, the word range in bold, and the character x in monospaced font

商标符号

如果您的 MATLAB 文件中的注释包括带商标的项，您可以包括文本以在输出中生成商标符号 (™) 或注册商标符号 (®)。只需紧随相关词语后添加 (R) 或 (TM)，之间不需要任何空格。

例如，假定您在一个文件中输入以下行。 

%% Basic Matrix Operations in MATLAB(R)
% This is a demonstration of some aspects of MATLAB(R)
% and the Symbolic Math Toolbox(TM).

如果您将文件发布为 HTML，它会显示在 HTML 查看器中。

Published document with a title and line of text that includes the word MATLAB with a registered trademark symbol next to it and the phrase Symbolic Math Toolbox with a trademark symbol next to it

项目符号和编号列表

MATLAB 允许在注释中使用项目符号列表和编号列表。您可以使用此语法生成项目符号列表和编号列表。

%% Two Lists
%
% * ITEM1 
% * ITEM2
%
% # ITEM1
% # ITEM2
%

发布该示例代码将生成以下输出。

Published document with a bulleted list followed by a numbered list. Each list contains two items: ITEM1 and ITEM2

文本和代码块

预设格式的文本

预设格式的文本显示为等宽字体，保留空白，且长行不换行。预设格式文本第一行的文本与注释符号之间必须留有两个空格。

发布此代码将生成预设格式的段落。

%%
% Many people find monospaced text easier to read:
%
%  A dot product of two vectors yields a scalar.
%  MATLAB has a simple command for dot products.

Published document with a line of text in the default font followed by two lines of text in monospaced font

语法高亮的示例代码

可执行代码显示在已发布文档中时语法会高亮显示。也可以高亮显示示例代码。示例代码是显示在注释中的代码。

要指示示例代码，您必须在注释符号与第一行代码的开头之间放置三个空格。例如，点击发布选项卡上的代码按钮可在您的编辑器中插入以下示例代码。

%%
%
%   for i = 1:10
%       disp(x)
%   end
%

将此代码发布为 HTML 可在 HTML 查看器中生成输出。

Published document with three lines of syntax-highlighted sample code

外部文件内容

要将外部文件内容添加到 MATLAB 发布的代码中，请使用 <include> 标记。指定外部文件路径（相对于所发布文件的位置）。所包含的 MATLAB 代码文件将发布为语法高亮显示代码。其他所有文件则发布为纯文本。

例如，此代码会将 sine_wave.m 的内容插入到发布的输出中：

%% External File Content Example
% This example includes the file contents of sine_wave.m into published
% output.
%
% <include>sine_wave.m</include>
%
% The file content above is properly syntax highlighted.

将文件发布为 HTML。

Published document with the contents of the file sine_wave.m displayed as syntax-highlighted code

外部图形

要发布 MATLAB 代码无法生成的图像，请使用文本标记。默认情况下，MATLAB 已包括代码生成的图形。

此代码将在发布的输出中插入名为 FILENAME.PNG 的普通图像。

%%
% 
% <<FILENAME.PNG>>
%

MATLAB 要求 FILENAME.PNG 是从输出位置到您的外部图像的相对路径，或者是完全限定 URL。最好将您的图像保存在 MATLAB 发布其输出的同一文件夹中。例如，MATLAB 将 HTML 文档发布到子文件夹 html。将您的图像文件保存在同一子文件夹中。您可以通过更改发布配置设置来更改输出文件夹。在 MATLAB Online™ 中，将您的图像文件保存到位于根文件夹下的 Published 文件夹中。

使用 surf(peaks) 的外部图形示例

此示例演示如何将 surfpeaks.jpg 插入到 MATLAB 文件中以便发布。

要创建 surfpeaks.jpg，请在命令行窗口中运行以下代码。

saveas(surf(peaks),'surfpeaks.jpg');

要从 MATLAB 文件生成包含 surfpeaks.jpg 的 HTML 文件，请执行以下操作：

  1. 在当前文件夹中创建一个名为 html 的子文件夹。

  2. 通过在命令行窗口中运行此代码创建 surfpeaks.jpg。 

    saveas(surf(peaks),'html/surfpeaks.jpg');

  3. 将此 MATLAB 代码发布为 HTML。

    %% Image Example
% This is a graphic:
%
% <<surfpeaks.jpg>>
%

    Published document with the surfpeaks.jpg image displayed

输出文件格式的有效图像类型

您在发布文档时可以纳入的图像类型取决于下表中注明的文档输出类型。为获得最佳兼容性，最好为每种输出类型使用默认图像格式。

输出文件格式默认图像格式您可以纳入的图像类型
docpng

所安装的 Microsoft® Office 版本支持的任何格式。

htmlpng

可成功发布任何格式。确保您用于查看和处理输出文件的工具可以显示指定的输出格式。

latexpng 或 epsc2

可成功发布任何格式。确保您用于查看和处理输出文件的工具可以显示指定的输出格式。

pdfbmp

bmp 和 jpg。

pptpng

所安装的 Microsoft Office 版本支持的任何格式。

xmlpng

可成功发布任何格式。确保您用于查看和处理输出文件的工具可以显示指定的输出格式。

图像快照

您可以插入捕捉您的 MATLAB 输出的快照的代码。例如，如果您有一个修改您要在每次迭代后捕获的图窗的 for 循环，这很有用。

下面的代码运行 for 循环三次并在每次迭代后生成输出。snapnow 命令捕获该代码生成的所有三个图像。

%% Scale magic Data and Display as Image

for i=1:3
    imagesc(magic(i))
    snapnow;
end

如果您将文件发布为 HTML，它将类似于以下输出。默认情况下，HTML 中的图像大于图窗中显示的图像。要调整 MATLAB 代码生成的图像的大小，请使用发布设置窗格中的最大图像宽度和最大图像高度字段，如用于发布的输出设置中所述。

Published document with code followed by the three images produced by the code displayed side by side

LaTeX 方程

行内 LaTeX 表达式

利用 MATLAB，您可以在想要发布的任何代码中包含行内 LaTeX 表达式。要插入行内表达式，请用美元符号字符 ($) 括起您的 LaTeX 标记。$ 必须紧靠在行内表达式第一个词的前面，以及紧跟在行内表达式最后一个词的后面，中间没有任何空格。

注意

  • 所有发布输出类型都支持 LaTeX 表达式，但 Microsoft PowerPoint® 除外。

  • MATLAB 发布支持标准 LaTeX 数学模式的指令。不支持文本模式的指令或需要额外包的指令。

此代码包含 LaTeX 表达式：

%% LaTeX Inline Expression Example
%
% This is an expression: $x^2+e^{\pi i}$. It is 
% inline with the text.

如果将示例文本标记发布为 HTML，结果输出如下。

Published document with a line of text containing an inline formatted expression

LaTeX 行间方程

在 MATLAB 中，您可以在与主注释文本相离的文本块中插入 LaTeX 符号。方程每侧添加两个美元符号 ($$) 表示 LaTeX 方程块。在单独的块中发布方程要求块之间存在空行。

此代码是示例文本标记。

%% LaTeX Equation Example
%
% This is an equation:
%
% $$e^{\pi i} + 1 = 0$$
%
% It is not in line with the text.

如果您发布为 HTML，方程如下所示。

Published document with text and a formatted equation on its own line

超链接

静态超链接

您可以在 MATLAB 注释中插入静态超链接，然后将文件发布为 HTML、XML 或 Microsoft Word 文件。在指定指向 Web 位置的静态超链接时，请在代码中包括完整的 URL。当您希望指引读者访问 Web 位置时，这很有用。您可以在已发布文本中显示或隐藏 URL。如果您确信读者是在线查看您的输出，并可以点击该超链接，则可考虑不包括 URL。

将 URL 和任何替代文本包括在尖括号中。

%%
% For more information, see our web site:
% <https://www.mathworks.com MathWorks>

将该代码发布为 HTML 将生成以下输出。

Published document with a line of text that contains the hyperlinked word MathWorks

消除 URL 后面的文本 MathWorks 可生成以下经过修改的输出。

Published document with a line of text containing a formatted URL

注意

如果您的代码在 MATLAB 命令行窗口中生成带超链接的文本，则输出显示 HTML 代码而非超链接。

动态超链接

您可以插入动态超链接，MATLAB 在读者点击该链接时执行它。通过动态超链接，您可指引读者访问 MATLAB 代码或文档，或使读者能够运行代码。您可以使用 matlab: 语法实现这些链接。如果紧随 matlab: 声明后的代码包含空格，则将其替换为 %20。

注意

仅当在 HTML 查看器中查看 HTML 时，动态链接才有效。

动态链接的不同用法包括：

用于运行代码的动态链接.  您可以指定动态超链接以在用户点击超链接时运行代码。例如，下面的 matlab: 语法在输出中创建超链接，点击该超链接时可启用或禁用回收：

%% Recycling Setting
% Click the setting you want:
%
% <matlab:recycle('off') Disable recycling>
%
% <matlab:recycle('on') Enable recycling>

发布的结果如以下 HTML 输出所示。

Published document with two lines of hyperlinked text: Disable recycling and Enable recycling

当您点击其中一个超链接时，MATLAB 会相应地设置 recycle 命令。点击超链接后，在命令行窗口中运行 recycle 以确认设置是否符合您的预期。

指向文件的动态链接.  您可以指定一个文件链接（您知道该文件位于您读者的 matlabroot 中）。您不需要知道每个读者安装 MATLAB 的位置。例如，指向 publish 函数代码的链接。

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

接下来，将文件发布为 HTML。

Published document with a line of text that includes the hyperlinked word code

当您点击 code 链接时，MATLAB 编辑器随即会打开并显示 publish 函数的代码。在读者的系统上，MATLAB 发出该命令（但该命令不显示在读者的命令行窗口中）。

指向 MATLAB 函数参考页的动态链接.  您可以使用 matlab: 语法指定指向 MATLAB 函数参考页的链接。例如，假设您的读者已安装并正在运行 MATLAB。提供指向 publish 参考页的链接。

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

将文件发布为 HTML。

Published document with a line of text that includes the hyperlinked word publish

当您点击 publish 超链接时，系统 Web 浏览器中将打开 publish 函数的参考页。在读者的系统上，MATLAB 发出该命令（但该命令不显示在命令行窗口中）。

HTML 标记

您可以将 HTML 标记插入到您的 MATLAB 文件中。您必须键入 HTML 标记，因为发布选项卡上没有可生成该标记的按钮。

注意

当您插入 HTML 代码的文本标记时，HTML 代码仅在指定的输出文件格式为 HTML 时才发布。

以下代码包括 HTML 标记。

%% HTML Markup Example
% This is a table:
%
% <html>
% <table border=1><tr><td>one</td><td>two</td></tr>
% <tr><td>three</td><td>four</td></tr></table>
% </html>
%

如果您将代码发布为 HTML，MATLAB 会创建一个包含两列的两行表。该表包含值 one、two、three 和 four。

Published document with a 2-by-2 table containing the words one, two, three, and four

如果某节生成以 <html> 开头并以 </html> 结尾的命令行窗口输出，则 MATLAB 在发布的输出中包括 HTML 源代码。例如，MATLAB 显示 disp 命令并根据 HTML 代码（如果您发布此代码）生成表：

disp('<html><table><tr><td>1</td><td>2</td></tr></table></html>')

Published document including the disp command followed by a 1-by-2 table containing the numbers 1 and 2

LaTeX 标记

您可以将 LaTeX 标记插入到您的 MATLAB 文件中。您必须键入所有 LaTeX 标记，因为发布选项卡上没有可生成该标记的按钮。

注意

当您插入 LaTeX 代码的文本标记时，该代码仅在指定的输出文件格式为 LaTeX 时才发布。

以下代码是 LaTeX 标记的一个示例。

%% LaTeX Markup Example
% This is a table:
%
% <latex>
% \begin{tabular}{|c|c|} \hline
% $n$ & $n!$ \\ \hline
% 1 & 1 \\
% 2 & 2 \\
% 3 & 6 \\ \hline
% \end{tabular}
% </latex>

如果您将文件发布为 LaTeX，则编辑器会打开一个新的包含 LaTeX 标记的 .tex 文件。

% This LaTeX was auto-generated from MATLAB code.
% To make changes, update the MATLAB code and republish this document.

\documentclass{article}
\usepackage{graphicx}
\usepackage{color}

\sloppy
\definecolor{lightgray}{gray}{0.5}
\setlength{\parindent}{0pt}

\begin{document}

    
    

\section*{LaTeX Markup Example}

\begin{par}
This is a table:
\end{par} \vspace{1em}
\begin{par}

\begin{tabular}{|c|c|} \hline
$n$ & $n!$ \\ \hline
1 & 1 \\
2 & 2 \\
3 & 6 \\ \hline
\end{tabular}

\end{par} \vspace{1em}



\end{document}

MATLAB 包括使用 LaTeX 程序编译此文件所需的任何其他标记。

另请参阅

主题