XCode 11.1 日本語化計画：Markup Formatting Reference

マークアップの文法

マークアップは、カスタムの拡張機能を備えた単純な、値引く札のような文字の区切り記号構文を使用します。以下の 4 つの型の要素があります。

• Single line (単一行) 要素は、見出しの作成など、テキストの行をフォーマットします。


• Multiline (複数行) 要素は、リストや呼び出しの作成など、複数行のテキストをフォーマットします。


• Span (スパン、期間) 要素は、強調を追加するなど、文字のスパンをフォーマットします。


• Link (リンク) 要素は、mailto などのテキストを基礎としたリンク、または画像などのインラインアセットを追加します。

単一行要素

単一行の要素は、開始の区切り文字を使用し、その後に少なくとも 1 つの空白が続き、その後に内容が続きます。

optional spaces delimiter …content

単一行の要素は以下の規則に従います。

• 区切り文字は、行の最初の空白でない文字です。


• 区切り文字と内容の間に少なくとも 1 つの空白があります。


• 区切り文字と内容の間の余分な空白は無視されます。


• 区切り文字とすべての内容は、新しい行によって終了されます。

たとえば、図 4-1 に示すように、以下のマークアップの行は両方とも同じ第 2 レベルの見出しとしてレンダリングされます。

1    //: ## Second Level Heading
2    //:   ##    Second Level Heading

図 4-1 見出しは空白を無視する

リンク要素

リンク要素は、リンク名とリンク目標を定義します。リンク名は、開き角括弧 ([) と閉じ角括弧 (]) の間に入力されます。アセットリンクは、開き角括弧の前の感嘆符 (!) で始まります。リンク要素の目標仕様は、通常、開き括弧 ([)と閉じ括弧 (]) の間にあります。リンク参照 の区切り文字では、括弧の代わりにコロン (:) の後に目標仕様が続きます。

optional link type character[link name](link target  link target options)

リンク要素は以下の規則に従います。

• リンク要素は、行のどこにでも表示できます。


• 区切り文字とすべての内容は、改行で終わる 1 行にあります。

例：URLリンク

以下のマークアップは、swift.org へのリンクとしてレンダリングされています。図 4-2 に示すように、リンクは、レンダリングされた文書にクリック可能な青いテキストとして表示されます。

図 4-2 テキストのリンク

例：インラインの画像

このマークアップは、cat という単語の後の行を中心としたリンクの画像内容をレンダリングします。図 4-3 に示すように、残りの内容は画像に続く行にレンダリングされます。

図 4-3 アセットのリンク

複数行の要素

リストや呼び出しなどの複数行の要素は、開始区切り文字を使用し、その後に少なくとも 1 つの空白が続き、次に内容が続きます。内容のブロックは、終了条件が満たされるまで続きます。

delimiter … line 1 content




optional continuation of line 1




optional newline




optional content


…

termination condition

複数行の要素は以下の規則に従います。

• 区切り文字は、行の最初の空白でない文字です。


• 区切り文字と内容の間に少なくとも 1 つの空白があります。


• 区切り文字と内容の間の余分な空白は無視されます。


• 単一の改行と、それに続くテキストは、テキストを前の行に包み込みます。


• 単一の空の行とそれに続くテキストは、新しい段落としてテキストを挿入します。

区切り文字は、以下の終了条件のいずれか 1 つになるまですべてのテキストをフォーマットします。

• 2 つ以上の連続した空の行


• ネストした同じレベルにある異なる行または複数行の区切り文字。

ネストした区切り文字

複数行要素のネストレベルは、4 つの空白の各セットまたは開始区切り文字の前の各タブで増加します。

ネストを使用して：

• リストのインデントレベルを上げる


• 見出しや横罫線などのネストした単一行要素を追加します


• コードブロック を追加する

連続するネストした行を追加するには、区切り文字で始まる各行に同じ数の初めの空白またはタブを追加します。空の行はインデントする必要はありません。

例：簡単な箇条書きリスト

以下のマークアップは、図 4-4 に示すように、クイックヘルプで 2 つの項目を含む箇条書きリストとしてレンダリングされます。

1   /**
2     * item 1
3     * item 2
4    */

図 4-4 簡単な箇条書きリスト

例：テキストラッピング

以下のマークアップは、図 4-5 に示すように、単一の番号付きリスト項目としてレンダリングされます。

1 /*:
2      1. This renders as
3       one line in
4      a numbered list
5     */

図 4-5 複数行要素でのラッピング

例：段落の挿入

このマークアップにより、図 4-6 に示すように、行 4 が最初の箇条書きの 2 番目の段落としてレンダリングされます。すべての段落の内容は、含まれる区切り文字と同じレベルにインデントされます。

1  /**
2       * A bullet item
3
4         With two paragraphs
5
6       * The next bullet item
7     */

図 4-6 段落の挿入

例：2 つの空の行を使用した呼び出しの終了

以下のマークアップは、図 4-7 に示すように 2 つの異なるリストとしてレンダリングされます。最初のリストは、マークアップの 4 行目と 5 行目の 2 つの連続した空の行で終了します。

1 /*:
2     1. First list, item 1
3     1. First list, item 2
4
5
6     1. Second list, item 1
7     */

図 4-7 空の行で終了する

例：異なる区切り文字でリストを終了する

このマークアップは、図 4-8 に示すように、それぞれ独自の見出しを持つ 2 つの異なるリストとしてレンダリングされます。5 行目の見出し区切り文字は、最初のリストを終了します。

1 /*:
2     ### List A
3     1. Item 1, List A
4     1. Item 2, List A
5     ### List B
6     1. Item 1, List B
7     */

図 4-8 異なる区切り文字での終了

例：ネストした区切り文字

このマークアップには、図 4-9 に示すように 3 種類のネストが含まれます。

1. ネストしたリストは、3 行目と 8 行目の各リスト項目の区切り文字の前に 4 つの空白を追加した結果です。


2. ネストしたコードブロックは、5 行目と 6 行目を 12 個の空白分インデントした結果であり、または囲む区切り文字から 2 レベルのインデントした結果です。


3. ネストした横罫線は、7 行を 8 個の空白またはインデントを囲む区切り文字から 1 レベルだけインデントした結果です。コードブロックの詳細については、コードブロック を参照してください。

1  /**
2      1. Level 1, Item 1
3         1. Level 2, Item 1
4
5                 func emptyFunc() {
6                 }
7             - - -
8         1. Level 2, Item 2
9      1. Level 1, Item 2
10     */

図 4-9 ネスト

スパン要素

スパン要素は、文字スパンの開始と終了で同じ区切り文字を使用します。

opening delimitercontentclosing delimiter

スパン要素は以下の規則に従います。

• 開始の区切り文字は、行の任意の場所に表示できます。


• 開始区切り文字とスパンの最初の文字の間に空白はありません。


• 最初の文字とスパンの終了区切り文字の間に空白はありません。


• スパンの途中にある単一の改行は無視され、テキストは最初の行にラッピングされます。


• スパン要素は組み合わせることができます。

例：空白の無視

以下のマークアップにより、図 4-10 に示すように 1 行のテキストが生成されます。

1    /// This markup renders as one *line
2    /// of text*

図 4-10 スパン要素のラッピング

例：要素の結合

このマークアップは、強調されたスパンの区切り文字内に太字のスパンの区切り文字を追加することを示しています。図 4-11 に示すように、レンダリングされた結果は、inside other に強調と太字の両方を追加します。

    //: Span elements *nest **inside other** span* elements

図 4-11 スパン要素の結合

単一の改行を無視

ほとんどの行とテキストをフォーマットする区切り文字内の単一の改行は無視され、行の末尾の空白とされます。

たとえば、以下のコードは 1 行目の終わりの改行を無視し、1 行のテキストが強調スタイルを使用してレンダリングされた on one line (一行) の単語のテキストになります。最初の行の末尾に空白を追加しても、on と one の単語の間に空白は追加されません。

1    //: This will all render *on
2    //: one line*

例外：リンク

テキストのリンクとメディアアセットのマークアップは、改行で終わる 1 行のテキストです。区切り文字と引数は、複数行にわたる場合、プレーンテキストとして扱われます。

テキストのリンクの区切り文字は、開き角かっこ ([) で始まります。メディアアセットの区切り文字は、感嘆符で始まり、その後に開き角かっこが続きます。(![)

たとえば、インラインビデオプレーヤーを指定するための区切り文字と引数の、以下のマークアップでは、2 行目と 3 行目にまたがっています。図 4-12 に示すように、3 行はすべてプレーンテキストとして扱われ、1 つのレンダリングされたテキストの行にまとめられます。

1    //: Watch the WWDC session introducing the San Francisco Font
2    //: ![San Francisco font introduction]
3    //: (new-fonts.mp4)

図 4-12 リンクはラップしない

すべての行を 1 行に結合すると、ビデオプレーヤーが表示されます。

前：ファイルにマークアップを追加 次：クイックヘルプの構文

マークアップの本質

マークアップの使用

マークアップ用のコメントマーカー

一行のテキストの構成

複数行のテキストの構成

文字のスパンの構文

リンクの挿入

アセットの挿入

コールアウトの挿入

Escaping Special Characters (特別な文字のエスケープ)

改訂履歴