パブリッシュマークアップ

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> %

セクションとセクションタイトル

コードセクションを使用すると、コードの整理、コメントの追加、コードの部分的実行ができます。コードセクションは 2 つのパーセント記号 (%%) で開始し、セクションタイトル (オプション) がその後に続きます。セクションタイトルは、大きい太字フォントで最上位レベルの見出し (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 は 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

テキストおよびコードのブロック

書式設定済みテキスト

書式設定済みテキストは、固定幅フォントで表示され、空白を保持しますが、長い行を改行しません。コメント記号と書式設定済みテキストの最初の行の間には、空白が 2 つ表示されなければなりません。

次のコードをパブリッシュすると書式設定済みの段落が生成されます。

%%
% 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

構文を強調表示したサンプルコード

パブリッシュされたドキュメント内では、実行可能コードの構文は強調表示されています。また、"サンプルコード" を強調表示することもできます。サンプルコードはコメント内に表示されるコードです。

サンプルコードを示すには、コメント記号とコードの最初の行の開始部分との間に空白を 3 つ入れなければなりません。たとえば、[パブリッシュ] タブの [コード] ボタンをクリックすると、次のサンプルコードがエディターに挿入されます。

%%
%
%   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');

surfpeaks.jpg を含んだ HTML ファイルを MATLAB ファイルから生成するには、次の手順に従います。

現在のフォルダーにサブフォルダー html を作成します。
このコードをコマンドウィンドウで実行して、surfpeaks.jpg を作成します。
```
saveas(surf(peaks),'html/surfpeaks.jpg');
```
この MATLAB コードを HTML にパブリッシュします。
```
%% Image Example
% This is a graphic:
%
% <<surfpeaks.jpg>>
%
```

出力ファイル形式の有効なイメージタイプ

パブリッシュするときに含めることができるイメージのタイプは、以下の表に示すように、そのドキュメントの出力タイプによって異なります。互換性を最大にするため、各出力タイプに既定のイメージ形式を使用することを推奨します。

出力ファイル形式	既定のイメージ形式	含められるイメージのタイプ
`doc`	`png`	インストールした Microsoft^® Office のバージョンがサポートする任意の形式。
`html`	`png`	すべての形式が正常にパブリッシュされます。指定した出力形式が出力ファイルを表示および処理するツールで表示できることを確認してください。
`latex`	`png` または `epsc2`	すべての形式が正常にパブリッシュされます。指定した出力形式が出力ファイルを表示および処理するツールで表示できることを確認してください。
`pdf`	`bmp`	`bmp` および `jpg`。
`ppt`	`png`	インストールした Microsoft Office のバージョンがサポートする任意の形式。
`xml`	`png`	すべての形式が正常にパブリッシュされます。指定した出力形式が出力ファイルを表示および処理するツールで表示できることを確認してください。

イメージのスナップショット

MATLAB 出力のスナップショットをキャプチャするコードを挿入できます。これは、for ループで各反復後にキャプチャする図を変更する場合などに便利です。

次のコードは for ループを 3 回実行し、各反復後に出力を生成します。snapnow コマンドは、コードで生成された 3 つのイメージをすべてキャプチャします。

%% 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 記号を挿入できます。式の両側にある 2 つのドル記号 ($$) が 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 関数リファレンスページへのダイナミックリンク

実行コードへのダイナミックリンク. ダイナミックハイパーリンクを指定して、ユーザーがハイパーリンクをクリックしたときにコードを実行できます。たとえば、次の 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

ハイパーリンクの 1 つをクリックすると、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 は 2 行 2 列の表を作成します。表には、値 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 マークアップの例です。

%% 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 プログラムでコンパイルするときに必要な追加マークアップが含まれています。

パブリッシュ マークアップ