initial commit

1 files changed, 250 insertions, 0 deletions

diff --git a/files/ja/mdn/structures/syntax_sections/index.html b/files/ja/mdn/structures/syntax_sections/index.html
new file mode 100644
index 0000000000..19b5bf3ee1
--- /dev/null
+++ b/files/ja/mdn/structures/syntax_sections/index.html
@@ -0,0 +1,250 @@
+---
+title: 構文の節
+slug: MDN/Structures/Syntax_sections
+tags:
+  - API
+  - CSS
+  - HTML
+  - MDN Meta
+  - Structure
+  - Syntax
+  - onboarding
+  - 進行中
+translation_of: MDN/Structures/Syntax_sections
+---
+<div>{{MDNSidebar}}</div>
+
+<p class="summary">MDN リファレンスページの構文の節には、機能が持つ正確な構文を定義する構文ボックスがあります (例えば、どのような引数が受け入れられるか、どれがオプションかなど)。この記事では、リファレンス記事の構文ボックスの書き方を説明します。</p>
+
+<h2 id="API_reference_syntax" name="API_reference_syntax">API リファレンスの構文</h2>
+
+<p>API リファレンスページの構文の節は手作業で書かれ、設置するページの種類によって異なります。しかし、共通事項もあります。いずれも節には「構文」という題名を付け、リファレンスページの最上部、導入部分のすぐ下に設置します。</p>
+
+<p>加えて、それぞれの構文の節はその機能の正確な構文を紹介する「構文」ブロックを、 "Syntax Box" ブロックスタイルを使用してスタイル付けしたもので始める必要があります。</p>
+
+<pre class="syntaxbox notranslate">A syntax block example</pre>
+
+<h3 id="General_style_rules" name="General_style_rules">全般的なスタイル規則</h3>
+
+<p>構文ブロック内をマークアップするために従うべき規則がいくつかあります。</p>
+
+<ul>
+ <li>構文ブロック内では (MDN のコード例の中でも) {{HTMLElement("code")}} を使用<em>しない</em>でください。これは一般的に意味がないだけでなく、これを含めると望み通りの表示が行われないので、マークアップしてほしくありません。</li>
+ <li>
+  <p>構文ブロック内でプログラマーに依存する部分は、 {{HTMLElement("em")}} を使用してイタリック体にしてください (エディターのツールバーの「斜体」ボタン)。</p>
+
+  <pre class="syntaxbox notranslate"><em>responseStr</em> = <em>element</em>.querySelector(<em>selector</em>);</pre>
+
+  <p>ここで、 <code>responseStr</code> は返値 (開発者が付ける変数名) であり、 <code>element</code> は {{DOMxRef("Element")}} オブジェクトを参照する変数のプレイスホルダーであり、 <code>selector</code> はメソッドの入力引数のプレイスホルダーです。</p>
+
+  <p>ページによっては <code>&lt;var&gt;</code> が <code>&lt;em&gt;</code> の代わりに使用されているのを見かけるかもしれません。これでも良いのですが、一般に <code>&lt;em&gt;</code> を推奨します。</p>
+ </li>
+</ul>
+
+<h3 id="Constructors_and_methods" name="Constructors_and_methods">コンストラクターやメソッドの場合</h3>
+
+<h4 id="Syntax_block" name="Syntax_block">構文ブロック</h4>
+
+<p>構文ブロックは、次のように始めてください ({{DOMxRef("IntersectionObserver.IntersectionObserver", "IntersectionObserver constructor")}} ページを参照)。</p>
+
+<pre class="syntaxbox notranslate">var <em>observer</em> = new IntersectionObserver(<em>callback</em>, <em>options</em>);</pre>
+
+<p>または、次のようにします ({{DOMxRef("WindowOrWorkerGlobalScope.fetch")}} を参照)。</p>
+
+<pre class="syntaxbox notranslate"><em>promiseResponse</em> = fetch(<em>input</em>, <em>init</em>);</pre>
+
+<p>構文は形式文法の表記を使用して書かれることもあります。例えば以下の {{jsxref("Array.prototype.slice()")}} を参照してください。</p>
+
+<pre class="syntaxbox notranslate">arr.slice([begin[, end]])</pre>
+
+<p>角括弧は内部の引数が省略可能であることを表します。これは読者の多くを混乱させるため、推奨しません。代わりに角括弧を外して、構文ブロックの下にある<em>引数</em>の節で、これらの引数が省略可能であることを説明したほうがいいでしょう。</p>
+
+<h5 id="Multiple_lines" name="Multiple_lines">複数行での表記</h5>
+
+<p>メソッドが複数の形式で使用されることがあるため、複数の行で記述したい場合があるでしょう。例えば、この ({{DOMxRef("CanvasRenderingContext2D.drawImage")}}) の例をご覧ください。</p>
+
+<pre class="syntaxbox notranslate">void <em>ctx</em>.drawImage(<em>image</em>, <em>dx</em>, <em>dy</em>);
+void <em>ctx</em>.drawImage(<em>image</em>, <em>dx</em>, <em>dy</em>, <em>dWidth</em>, <em>dHeight</em>);
+void <em>ctx</em>.drawImage(<em>image</em>, <em>sx</em>, <em>sy</em>, <em>sWidth</em>, <em>sHeight</em>, <em>dx</em>, <em>dy</em>, <em>dWidth</em>, <em>dHeight</em>);</pre>
+
+<p><code>slice()</code> の構文の例も、すべての変化形を表示し理解しやすくするために、次のように書き直すことができます。</p>
+
+<pre class="syntaxbox notranslate"><var>arr</var>.slice()<var>
+arr</var>.slice(<var>begin</var>)
+<var>arr</var>.slice(<var>begin</var>, <var>end</var>)</pre>
+
+<p>他の複数行の例として、 {{jsxref("Date")}} コンストラクターのページでは、取りうる引数の組み合わせが全く異なる形でたくさんあることを示しています。</p>
+
+<pre class="syntaxbox notranslate">new Date();
+new Date(<var>value</var>);
+new Date(<var>dateString</var>);
+new Date(<var>year</var>, <var>monthIndex</var> [, <var>day</var> [, <var>hours</var> [, <var>minutes</var> [, <var>seconds</var> [, <var>milliseconds</var>]]]]]);
+</pre>
+
+<p>ただし前述の通り、角括弧を外し、<em>引数</em>の節で引数が省略可能であることを明確にするべきでしょう。</p>
+
+<h5 id="Concise_syntax_blocks" name="Concise_syntax_blocks">構文ブロックは簡潔に</h5>
+
+<p>構文ブロックを簡潔にし、その機能の構文の定義の曖昧さをなくすために — 無関係な構文を含めないでください。例えば、このサイトの多くの場所で、 Promise を説明するために次のような形をよく見かけます。</p>
+
+<pre class="syntaxbox notranslate"><em>caches</em>.match(<em>request</em>, <em>options</em>).then(function(<em>response</em>) {
+  // Do something with the response
+});</pre>
+
+<p>しかし、次のものははるかに簡潔で、余計な {{JSxRef("Promise.prototype.then()")}} メソッド呼び出しを含んでいません。</p>
+
+<pre class="syntaxbox notranslate"><em>promiseResponse</em> = <em>caches</em>.match(<em>request</em>, <em>options</em>);</pre>
+
+<h4 id="Parameters_section" name="Parameters_section">引数の項</h4>
+
+<p>次に、「引数」の項を設置して、それぞれの引数が何であるべきかを説明リストの形で説明してください。複数のメンバーを含むことができるオブジェクトの引数は、入れ子の説明リストで記述し、その中にそれぞれのメンバーが何であるべきかを記述してください。省略可能な引数は、説明する用語の名前の隣に \{{optional_inline}} マクロでマークしてください。</p>
+
+<p>リスト内の各引数の名前は {{HTMLElement("code")}} ブロックの中に含めてください。</p>
+
+<div class="note">
+<p><strong>メモ</strong>: その機能が何も引数を取らない場合は、「引数」の項を設置する必要はありませんが、中身を「なし」として設置しても構いません。</p>
+</div>
+
+<h4 id="Return_value_section" name="Return_value_section">返値の項</h4>
+
+<p>その次に、「返値」の項を設置して、コンストラクターやメソッドの返値が何であるかを説明してください。 <code>undefined</code> の場合にも記述します。例については前述のリンクを参照して下さい。</p>
+
+<h4 id="Exceptions_section" name="Exceptions_section">例外の項</h4>
+
+<p>最後に、「例外」の項を設置して、コンストラクターやメソッドの呼び出し時に問題が発生した場合にどの例外が発生するかを説明してください。発生する原因としては、引数名の綴りが間違っていたり、間違ったデータ型の値が与えられたり、呼び出された環境に問題があったり (例えば、安全なコンテキストで実行する機能を安全でないコンテキストで実行しようとした場合など)、その他の理由であったりする場合などです。</p>
+
+<p>メソッドで発生する例外を特定するには、仕様を十分に精査する必要があります。機能がどのように動作するかについて、仕様書の1つ1つの説明を調べると、一般に例外とそれが発生する状況の確実な一覧を得ることができます。</p>
+
+<p>例外の名前と説明を説明リストに記述してください。</p>
+
+<div class="note">
+<p><strong>メモ</strong>: その機能で発生する例外がない場合は「例外」の項を設置する必要はありませんが、中身を「なし」として設置しても構いません。</p>
+</div>
+
+<h3 id="Properties" name="Properties">プロパティの場合</h3>
+
+<h4 id="Syntax_block_2" name="Syntax_block_2">構文ブロック</h4>
+
+<p>次のように構文ブロックで始めてください ({{DOMxRef("IntersectionObserver.root")}} を参照)。</p>
+
+<pre class="syntaxbox notranslate"><var>var <em>root</em> = IntersectionObserver</var>.root;</pre>
+
+<p>読み取り専用のプロパティではない場合は、二行を使ってプロパティの取得と設定の両方を示すのもいいでしょう ({{DOMxRef("AudioParam.value")}} を参照)。</p>
+
+<pre class="syntaxbox notranslate"><em>gain</em> = <em>gainNode</em>.gain.value;
+<em>gainNode</em>.gain.value = 0;</pre>
+
+<h4 id="Value_section" name="Value_section">値の項</h4>
+
+<p>構文ブロックの下に「値」の項を設置する必要があり、そこでプロパティの値を — データ型とその用途について — 説明してください。</p>
+
+<h4 id="Exceptions_section_2" name="Exceptions_section_2">例外の項</h4>
+
+<p>プロパティにアクセスする際に例外が発生する可能性がある場合、「例外」の項を設置してそれぞれの例外を説明してください。これは前述のメソッドやコンストラクターの説明と同様のことをしてください。</p>
+
+<h3 id="Event_handlers" name="Event_handlers">イベントハンドラーの場合</h3>
+
+<p>イベントハンドラープロパティは確かにプロパティですが、構文の節の中ではいくらかの違いがあります。</p>
+
+<h4 id="Syntax_block_3" name="Syntax_block_3">構文ブロック</h4>
+
+<p>次のように構文ブロックで始めてください ({{DOMxRef("Window.onvrdisplaypresentchange")}} を参照)。</p>
+
+<pre class="syntaxbox notranslate"><em>window</em>.onvrdisplaypresentchange = <em>functionRef</em>;</pre>
+
+<p>以上で十分です。 — イベントハンドラープロパティは常に設定可能で、常に関数が設定されるため、これ以上の情報は不要です。</p>
+
+<h2 id="JavaScript_reference_syntax" name="JavaScript_reference_syntax">JavaScript リファレンスの構文</h2>
+
+<p>JavaScript 組込みオブジェクトのリファレンスページは、 API リファレンスページと同様の基本規則に従います。例えばメソッドやプロパティについてです。多少の違いが見られることがあります。</p>
+
+<ul>
+ <li>組込みオブジェクトで単一のコンストラクターを持つものは、コンストラクターの構文がオブジェクトのランディングページに含まれていることが良くあります。例えば {{JSxRef("Date")}} を参照してください。 (<code>Date</code> オブジェクト自身が持つ) 静的メソッドは、「メソッド」の下の「Date.prototype メソッド」で記述されていることが分かるでしょう。</li>
+ <li>また、引数も例外もないメソッドは、 JavaScript リファレンスページにこれらの節が全く含まれていないことに気が付くでしょう。例えば {{JSxRef("Date.getDate()")}} や {{JSxRef("Date.now()")}} を参照してください</li>
+</ul>
+
+<h2 id="CSS_reference_syntax" name="CSS_reference_syntax">CSS リファレンスの構文</h2>
+
+<h3 id="Properties_2" name="Properties_2">プロパティ</h3>
+
+<p>CSS プロパティページには「構文」の節があり、ふつうはページの先頭にありますが、次第に、機能の典型的な使用方法を示すブロックを含む節や、その機能が何を行うかを説明するライブデモ (例えば {{CSSxRef("animation")}} を参照) の下に見られるようになっています。</p>
+
+<div class="note">
+<p><strong>メモ</strong>: このようにしているのは、 CSS の形式文法が複雑であり、 MDN の読者の多くが必要としておらず、初心者にとってとっつきにくいからです。実際の構文と例が多くの人にとってより有用です。</p>
+</div>
+
+<p>構文の節の中には、次のような内容が見られるでしょう。</p>
+
+<h4 id="Optional_explanation_text" name="Optional_explanation_text">説明文は任意</h4>
+
+<p>CSS プロパティによってはそれ自体が説明的であり、それ以上の説明が本当に必要ない場合があります (例えば {{CSSxRef("color")}})。一方、より複雑で、複数の値などを含む構文の順序の説明が必要なものもあります ({{CSSxRef("animation")}} を参照)。そのような場合、項が始まる前に追加の説明を加えることができます。</p>
+
+<h4 id="Values_section" name="Values_section">値の項</h4>
+
+<p>次に、「値」の項を入れてください。 — これには説明リストが入り、プロパティの値を構成する値の型を説明します。値の型はそれぞれ山括弧で囲み、その値の型を説明する MDN のリファレンスページがあれば、そこへリンクしてください。例えば、 {{CSSxRef("border")}} プロパティのリファレンスを参照してください。 — これは3つの値の型を参照しており、そのうちの一つ ({{CSSxRef("&lt;color&gt;")}}) だけがリンクになっています。</p>
+
+<h4 id="Formal_syntax" name="Formal_syntax">形式文法</h4>
+
+<p>最後の項、「形式文法」は <a href="https://github.com/mdn/data">MDN data リポジトリ</a>の CSS ディレクトリにあるデータから自動的に生成されます。タイトルの下で {{TemplateLink("CSSSyntax")}} マクロ呼び出しを記述するだけで、残りのことはマクロがやってくれます。</p>
+
+<p>唯一の問題は、必要なデータが存在することを確認することです。 <a href="https://github.com/mdn/data/blob/master/css/properties.json">properties.json</a> ファイルに、文書化しているプロパティの項目が含まれている必要があり、 <a href="https://github.com/mdn/data/blob/master/css/types.json">types.json</a> ファイルには、プロパティの値で使用されるすべての値の型の項目が含まれている必要があります。</p>
+
+<p>これを行うには、 <a href="https://github.com/mdn/data">MDN data リポジトリ</a>をフォークし、フォークをローカルにクローンし、新しいブランチに変更を行い、上流のリポジトリに向けてプルリクエストを送信してください。 <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#Preparing_to_add_the_data">Git の使用についての詳細はこちらにあります</a>。</p>
+
+<h3 id="Selectors" name="Selectors">セレクター</h3>
+
+<p>セレクターのリファレンスページの「構文」の節は、プロパティページよりもずっと簡潔です。ここには "Syntax Box" を使用してスタイル付けされたブロックが1つ入り、ここでセレクターの基本的な構文を、単純なキーワードだけ (例えば {{CSSxRef(":hover")}}) または引数を取るより複雑な関数値 (例えば {{CSSxRef(":not", ":not()")}}) のどちらかで示します。引数を構文ブロックの中の別な項目で説明している場合もあります (例えば {{CSSxRef(":nth-last-of-type", ":nth-last-of-type()")}} を参照してください)。</p>
+
+<p>このブロックは、 <a href="https://github.com/mdn/data">MDN data リポジトリ</a>の CSS ディレクトリにあるデータから自動的に生成されます。題名の下で {{TemplateLink("CSSSyntax")}} マクロ呼び出しを追加するだけで、残りのことはマクロがやってくれます。</p>
+
+<p>唯一の問題は、必要なデータが存在することを確認することです。 <a href="https://github.com/mdn/data/blob/master/css/selectors.json">selectors.json</a> ファイルに、文書化しているセレクターの項目が含まれている必要があります。</p>
+
+<p>これを行うには、 <a href="https://github.com/mdn/data">MDN data リポジトリ</a>をフォークし、フォークをローカルにクローンし、新しいブランチに変更を行い、上流のリポジトリに向けてプルリクエストを送信してください。 <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#Preparing_to_add_the_data">Git の使用についての詳細はこちらにあります</a>。</p>
+
+<h2 id="HTML_reference_syntax" name="HTML_reference_syntax">HTML リファレンスの構文</h2>
+
+<p>HTML リファレンスページには「構文」の節がありません。 — 構文は常に要素名を山括弧で囲んだものであるため、必要ないからです。 HTML 要素について主に知っておかなければならないことは、どのような属性を取りうるか、その値は何になるかであり、これは別の「属性」の節で扱います。例としては、 {{htmlelement("ol")}} や {{htmlelement("video")}} をご覧ください。</p>
+
+<h2 id="HTTP_reference_syntax" name="HTTP_reference_syntax">HTTP リファレンスの構文</h2>
+
+<p>HTTP リファレンスの構文はすべて手作業で作成され、文書化する HTTP の機能によって異なります。</p>
+
+<h3 id="HTTP_headersContent-Security-Policy" name="HTTP_headersContent-Security-Policy">HTTP ヘッダー/Content-Security-Policy</h3>
+
+<p>HTTP ヘッダーの構文 (および Content-Security-Policy) ページ上で二つの節に分けて記述します。 — 「構文」と「ディレクティブ」です。</p>
+
+<h4 id="Syntax_section" name="Syntax_section">構文の節</h4>
+
+<p>「構文」の節は、ヘッダーの構文がどのようなものかを、 "Syntax Box" スタイルを使用してスタイル付けされた構文ブロックを用いて、値にどのディレクティブが含まれるか、どのような順番かなどの形式文法を含めて示します。例えば、 {{HTTPHeader("If-None-Match")}} ヘッダーの構文ブロックは次のようになります。</p>
+
+<pre class="syntaxbox notranslate">If-None-Match: &lt;etag_value&gt;
+If-None-Match: &lt;etag_value&gt;, &lt;etag_value&gt;, …
+If-None-Match: *</pre>
+
+<p>ヘッダーによっては個別にリクエストディレクティブ、レスポンスディレクティブ、拡張構文があることがあります。存在する場合、それぞれの項の下にある個別の構文ブロックの中に設置する必要があります。例としては {{HTTPHeader("Cache-Control")}} をご覧ください。</p>
+
+<h4 id="Directive_section" name="Directive_section">ディレクティブの節</h4>
+
+<p>「ディレクティブ」の節には、構文に現れる可能性があるすべてのディレクティブの名前と解説を記述した説明リストを設定します。</p>
+
+<h3 id="HTTP_request_methods" name="HTTP_request_methods">HTTP リクエストメソッド</h3>
+
+<p>リクエストメソッドの構文は実に単純で、構文ブロックを設置し、 "Syntax Box" スタイルを用いてスタイル付けし、どのようにメソッドの構文を構成するかを示すだけです。 <a href="/ja/docs/Web/HTTP/Methods/GET">GET メソッド</a>の構文は次のようになります。</p>
+
+<pre class="syntaxbox notranslate">GET /index.html</pre>
+
+<h3 id="HTTP_response_status_codes" name="HTTP_response_status_codes">HTTP レスポンスステータスコード</h3>
+
+<p>HTTP レスポンスステータスコードの構文も、実に単純です。 — コードと名前を含む構文ブロックです。例えば次のようになります。</p>
+
+<pre class="syntaxbox notranslate">404 Not Found</pre>
+
+<h2 id="SVG_reference_syntax" name="SVG_reference_syntax">SVG リファレンスの構文</h2>
+
+<h3 id="SVG_elements" name="SVG_elements">SVG 要素</h3>
+
+<p>SVG 要素に構文の節は存在しません。 — HTML 要素の構文の節と同様です。それぞれの SVG 要素のリファレンスページは、その要素に適用することができる属性の一覧を含みます。例えば {{SVGElement("feTile")}} を参照してください。</p>
+
+<h3 id="SVG_attributes" name="SVG_attributes">SVG 属性</h3>
+
+<p>SVG 属性のリファレンスページにも、構文の節はありません。</p>