Skip to content

Commit

Permalink
markdownlintで指摘される問題をおおむね解消 (#213)
Browse files Browse the repository at this point in the history
  • Loading branch information
@momdo
momdo authored Oct 8, 2021
1 parent 8578c77 commit f40cdab
Show file tree
Hide file tree
Showing 11 changed files with 43 additions and 53 deletions.
7 changes: 3 additions & 4 deletions md_text/1-3.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,10 @@ HTMLが形式的に仕様に従っているだけでは、今日のHTML仕様を
<h1>これは見出しのテキストのかたまりです</h1>
<p>これは本文です。この<strong>キーワード</strong>はこの文章で重要なものを表します。</p>
```

字句的にも語彙的にも当然問題ありません。この例では見出しを`h1`、本文を`p`というタグでマークアップしており、意味論的にも問題ありません。ここで、試しに要素を入れ替えるとどうなるでしょうか。

(よくない例)
<!--(よくない例)-->
```html
<p>これは見出しのテキストのかたまりです</p>
<h1>これは本文です。この<strong>キーワード</strong>はこの文章で重要なものを表します。</h1>
Expand Down Expand Up @@ -114,7 +115,7 @@ HTMLをNu Html Checkerでチェックすると、エラーとは別に警告(War

[^1]: https://validator.w3.org/

[^2]: https://checker.html5.org/ nuとnewは同じ発音ですから、そういった意味が込められているのでしょう。
[^2]: <https://validator.w3.org/nu/> nuとnewは同じ発音ですから、そういった意味が込められているのでしょう。

## コラム: 仕様のアップデート

Expand All @@ -140,7 +141,6 @@ HTMLをNu Html Checkerでチェックすると、エラーとは別に警告(War

また、適切なマークアップは不必要に煩雑なマークアップを回避することにもなります。その結果としてマークアップを簡潔にすることにつながるため、HTMLファイルの容量の肥大化を防ぐことができます。


### メンテナンス性の向上

HTML仕様に従って作成されている適切なマークアップは、HTMLコードの見通しを良くし、将来への互換性を担保することができます。
Expand All @@ -163,7 +163,6 @@ HTML仕様に従って作成されている適切なマークアップは、HTML

これはいわゆるSEO（サーチエンジン最適化）とも重なる部分があると言えます。適切にマークアップすることにより、サーチエンジンに対してより検索しやすいウェブページを提供することができるのです。


## コラム: 人に優しく、自分に厳しく

インターネットの世界では、“送信するものに関しては厳密に、受信するものに関しては寛容に”という原則があります。これは「ポステルの法則」(Postel's law)と呼ばれています。
Expand Down
7 changes: 3 additions & 4 deletions md_text/1-4.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,6 @@ IETF (Internet Engineering Task Force)は、インターネット技術の標準

RFCは、IETFで定められた必要な議論や手続きを経たインターネットの技術的な約束事ばかりでなく、インターネットを利用する上で参考となるような情報、はたまたエイプリルフールにジョークとして公開されるものまで、さまざまな文書が存在します。RFCは通常、Internet-Draftと呼ばれるドラフト文書を経てRFCとなります。RFCはいくつかの種類に分類されます。


表 1.4-1 RFC文書の分類の一部

| 略称 | 分類名 | 分類の説明 |
Expand All @@ -51,7 +50,7 @@ RFCは、IETFで定められた必要な議論や手続きを経たインター

### コラム：RFCの略称と時代背景

RFCは、Request For Commentsの略で“意見を求む”といった意味です。しかし、インターネットに関連する技術標準を示す文書の名称が、なぜ意見を求めているのでしょうか。
RFCは、Request For Commentsの略で“意見を求む”といった意味です。しかし、インターネットに関連する技術標準を示す文書の名称が、なぜ意見を求めているのでしょうか。

これは、インターネットの生い立ちと時代背景によるものです。インターネットの前身は、米国国防総省国防高等研究計画局（DARPA, Defense Advanced Research Project Agency）が開発を進めたAPRAネットというものでした。

Expand All @@ -76,7 +75,7 @@ HTML 3.2では、HTML 2.0の要素に加え、`table`要素が取り込まれた

なお、ほぼ同時期の1996年12月に、スタイルシートの仕様であるCSS1[^6]がW3C勧告となっています。しかし、HTML 3.2では、スタイルシートを扱う`style`要素は予約語とされているだけで定義はされておらず、正式にはスタイルシートを扱うことのできない仕様になっていました。

[^6]: Cascading Style Sheets, level 1 https://www.w3.org/TR/REC-CSS1/
[^6]: Cascading Style Sheets, level 1 <https://www.w3.org/TR/REC-CSS1/>

### W3Cと勧告トラック

Expand Down Expand Up @@ -155,4 +154,4 @@ XHTMLを使うことで、HTML 4の要素をXMLの文法で書くことができ

[^11]: https://www.w3.org/TR/xhtml11/

[^12]: Ruby Annotation https://www.w3.org/TR/ruby/
[^12]: Ruby Annotation <https://www.w3.org/TR/ruby/>
1 change: 0 additions & 1 deletion md_text/1-5.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,6 @@ HTML 5.0から2年ものブランクがあった理由は、いくつかの要

と記載されています。2021年1月に発行されたReview Draft[^4]はW3C Recommendationとして認定され、HTML 5.1とHTML 5.2はHTML 5.0と同様に廃止されました。これにより、W3Cが勧告したすべてのHTMLは廃止され、WHATWG HTMLが名実ともに唯一のHTML仕様となったのです。


[^3]: <https://www.w3.org/2018/10/w3c-highlights/>

[^4]: <https://html.spec.whatwg.org/review-drafts/2020-01/>
Expand Down
7 changes: 3 additions & 4 deletions md_text/1-6.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,15 +47,15 @@ HTML仕様の1章には、"How to read this specification"というズバリそ

なお、WHATWG標準の共通ルールは"Infra"という文書にまとめられています[^2]。用語の使い方や記述ルールはこちらもあわせて参照する必要があります。

[^2]: Infra Standard https://infra.spec.whatwg.org/
[^2]: Infra Standard <https://infra.spec.whatwg.org/>

### 目次から探す

多くの場合は、目次から必要な箇所だけを探して読むという使い方になるでしょう。仕様書の表紙ページには目次があり、見たい章に飛ぶことができます。
とはいえ、初見ではどの章に何が書かれているのかわからないことも多いでしょう。以下に、よくありそうな用途と、その情報が執筆時点でどの章に書かれているかを簡単に紹介します。
なお、仕様にも各章の簡単な説明が記載されています[^3]。

[^3]: 1.9 Structure of this specification https://html.spec.whatwg.org/multipage/introduction.html#structure-of-this-specification
[^3]: 1.9 Structure of this specification <https://html.spec.whatwg.org/multipage/introduction.html#structure-of-this-specification>

#### HTMLの要素について詳しく知りたい

Expand Down Expand Up @@ -100,7 +100,7 @@ HTMLの文法(シンタックス)については、12章に記載があります

HTML仕様には索引のページも存在します[^4]。目当ての要素や属性についてピンポイントで調べたい場合は、索引にアクセスしてページ内検索で検索してしまうのも手です。

[^4]: Index https://html.spec.whatwg.org/multipage/indices.html
[^4]: Index <https://html.spec.whatwg.org/multipage/indices.html>

![HTML仕様の索引（属性）のスクリーンショット](../img/1-6-02.png)

Expand Down Expand Up @@ -182,7 +182,6 @@ HTML標準に限らず一般的に仕様は、他の仕様に依存していま

例えば、小文字でRFC 2119キーワードを示すことは、RFC 8174への故意の違反に当たります。


## HTML以外の仕様

ウェブページを制作する際には、HTMLだけでなく、CSSやJavaScriptの仕様を参照することもあるでしょう。すでに紹介したように、HTMLはWHATWGが仕様を策定していますが、CSSはW3C、JavaScriptはEcma Internationalと、各技術はそれぞれ別々の標準化団体によって策定されています。
Expand Down
4 changes: 2 additions & 2 deletions md_text/2-1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,14 +82,14 @@ HTMLでは、この情報を「タグ」(tag)と呼ばれるマークを使っ

ある要素の終了タグが省略できるかどうか、省略できるのはどのような場合かは、仕様書の各要素の説明に書かれています。たとえば、`mark`要素[^2]の場合は、以下のように書かれています。

[^2]: 4.5.23 mark要素 https://momdo.github.io/html/text-level-semantics.html#the-mark-element
[^2]: 4.5.23 The mark element <https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-mark-element>

>text/htmlにおけるタグ省略：
>どちらのタグも省略不可。
これは、開始タグも終了タグも省略できないという意味です。一方、`p`要素[^3]の場合は、以下のような記述があります。

[^3]: 4.4.1 p要素 https://momdo.github.io/html/grouping-content.html#the-p-element
[^3]: 4.4.1 The p element <https://html.spec.whatwg.org/multipage/grouping-content.html#the-p-element>

>text/htmlにおけるタグ省略：
>p要素がaddress、article、aside、blockquote、details、div、dl、fieldset、figcaption、figure、footer、form、h1、h2、h3、h4、h5、h6、header、hgroup、hr、main、menu、nav、ol、p、pre、section、table、ul要素の直後に存在する場合、または親要素で追加のコンテンツが存在せずかつ親要素がa、audio、del、ins、map、noscript、video要素、または自律カスタム要素でないHTML要素である場合、p要素の終了タグは省略することができる。
Expand Down
2 changes: 1 addition & 1 deletion md_text/2-6.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ HTMLでは、名前付き文字参照が延べ2230種類[^1]定義されてい

それに対し、たとえば`amp;`の場合、セミコロンがない`amp`も登録されています。そのため、`&amp`と書いてセミコロンを書き忘れても、エラー処理[^3]の結果として文字参照が有効になり、`&`に展開されます。ただし、属性値の中ではエラー処理の結果が異なり、セミコロンのない文字参照は無効となって、書いたままの文字列`&amp`として解釈されます。

[^3]: 具体的には“missing-semicolon-after-character-reference parse error”となる。12.2.5.73 Named character reference state https://momdo.github.io/html/parsing.html#parse-error-missing-semicolon-after-character-reference を参照。
[^3]: 具体的には“missing-semicolon-after-character-reference parse error”となる。13.2.5.73 Named character reference state <https://html.spec.whatwg.org/multipage/parsing.html#named-character-reference-state> を参照。

|書いた内容|処理結果|備考|
|----|----|----|
Expand Down
10 changes: 4 additions & 6 deletions md_text/3-2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

この節では、セクションと密接に関係する見出しと、セクションに付随する概念であるアウトラインとランドマークについて説明し、文書全体の構造を表現することを考えてみます。

## セクション
## セクションとは

セクション（section）は、一般には区分や区画といった意味を持ちます。特に書籍や文章の一部分として、節という訳語が当てられます。

Expand Down Expand Up @@ -98,7 +98,6 @@ HTML仕様ではこのアウトラインを機械的に取得する方法が「

図3-02-03 典型的なランドマークパターン


WAI-ARIA仕様では、ランドマークロールとして8種類の`role`の値が定義されており、これによりランドマークを表現することができます[^1]。

その一方、HTMLではWAI-ARIA仕様でランドマークロールに分類された`role`の値に対応する要素が用意されています。この章で紹介するものでは、`nav`要素、`aside`要素、`header`要素、`footer`要素が該当します。
Expand All @@ -120,6 +119,7 @@ WAI-ARIA仕様では、ランドマークロールとして8種類の`role`の
| | +2.1節見出し +2.2節見出し |
+-1章見出し +-2章見出し +3章見出し
```

図3-02-04 ページを音声ファイルに見立てた場合の見出しイメージ

見出しの情報は、ウェブアクセシビリティの観点から重要視されています。スクリーンリーダーの利用者は、見出しのみを読み上げさせたり、見出しにジャンプしたりするような使い方をすることが多いようです。
Expand All @@ -141,8 +141,8 @@ WAI-ARIA仕様では、ランドマークロールとして8種類の`role`の
| | | |
+-ﾍｯﾀﾞｰ +-ﾅﾋﾞ +主要ｺﾝﾃﾝﾂ +ﾌｯﾀｰ
```
図3-02-05 ページを音声ファイルに見立てた場合のランドマークイメージ

図3-02-05 ページを音声ファイルに見立てた場合のランドマークイメージ

なお、WCAG 2.1 の達成基準2.4.1 "Bypass Blocks"[^4]では、こういったサイト内の共通要素を読み飛ばせるようにすることを求めています。

Expand Down Expand Up @@ -186,7 +186,7 @@ HTMLには「見出し」(heading) を表現する要素が用意されていま
<p>本文の続きです</p>
```

```
```plaintext
+- - - 暗黙のセクション -+
| 見出し1 |
| 最初の本文です |
Expand Down Expand Up @@ -267,7 +267,6 @@ HTMLには「見出し」(heading) を表現する要素が用意されていま

このように表現すると、階層によって見出しのマークアップを変更する必要がないというメリットもあります。見出しを含むHTMLの部品をコンポーネントとして使い回す際、従来の方法では、出現場所に応じて見出しのレベルを変更する必要がありました。この方法なら、完全に同じHTMLのまま使い回すことができます。


#### コラム：見出しランクとの併用

セクショニングコンテンツの入れ子と、見出しランクによる暗黙のセクションは併用することもできます。以下はHTML仕様に出ているマークアップ例です。
Expand Down Expand Up @@ -394,7 +393,6 @@ HTMLには「見出し」(heading) を表現する要素が用意されていま
└ Apples
```


## `body`要素

`body`要素は、文書のコンテンツを表します。`head`要素内のメタデータが原則として画面に表示されないものだったのに対し、こちらは原則として表示される内容を記述するセクションと言えます。`html`要素の2番目の子として、つまり`head`要素の弟として、HTML文書に必ず1つのみ存在します。
Expand Down
37 changes: 18 additions & 19 deletions md_text/3-3.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -329,15 +329,15 @@ after.txt を上書きしますか? (Yes/No/All): <kbd>No</kbd>
<!-- MDNからの借り物改 -->
```html
<ol>
<li>1番目の項目</li>
<li>2番目の項目 <!-- ここには終了タグはない -->
<ol>
<li>2番目の項目の、1番目のサブ項目</li>
<li>2番目の項目の、2番目のサブ項目</li>
<li>2番目の項目の、3番目のサブ項目</li>
</ol>
</li> <!-- ここに終了タグを記述し、要素を閉じる -->
<li>3番目の項目</li>
<li>1番目の項目</li>
<li>2番目の項目 <!-- ここには終了タグはない -->
<ol>
<li>2番目の項目の、1番目のサブ項目</li>
<li>2番目の項目の、2番目のサブ項目</li>
<li>2番目の項目の、3番目のサブ項目</li>
</ol>
</li> <!-- ここに終了タグを記述し、要素を閉じる -->
<li>3番目の項目</li>
</ol>
```
<!-- /内容モデル -->
Expand All @@ -360,15 +360,15 @@ after.txt を上書きしますか? (Yes/No/All): <kbd>No</kbd>
<!-- MDNからの借り物改 -->
```html
<ul>
<li>(順番が重要でない) 1番目の項目</li>
<li>(順番が重要でない) 2番目の項目 <!-- ここには終了タグはない -->
<ol>
<li>2番目の項目の、(順番に意味がある) 1番目のサブ項目</li>
<li>2番目の項目の、(順番に意味がある) 2番目のサブ項目</li>
<li>2番目の項目の、(順番に意味がある) 3番目のサブ項目</li>
</ol>
</li> <!-- ここに終了タグを記述し、要素を閉じる -->
<li>(順番が重要でない) 3番目の項目</li>
<li>(順番が重要でない) 1番目の項目</li>
<li>(順番が重要でない) 2番目の項目 <!-- ここには終了タグはない -->
<ol>
<li>2番目の項目の、(順番に意味がある) 1番目のサブ項目</li>
<li>2番目の項目の、(順番に意味がある) 2番目のサブ項目</li>
<li>2番目の項目の、(順番に意味がある) 3番目のサブ項目</li>
</ol>
</li> <!-- ここに終了タグを記述し、要素を閉じる -->
<li>(順番が重要でない) 3番目の項目</li>
</ul>
```
<!-- /内容モデル -->
Expand Down Expand Up @@ -566,7 +566,6 @@ Either: Zero or more groups each consisting of one or more dt elements followed
また、`main`要素は基本的に`body`要素の直下に置く必要があります。`div`要素やアクセシブルな名前を持たない`form`要素を挟むことは許されますが、他の意味のある要素の子孫要素にすることはできません。このため、`main`要素を他のランドマーク要素の中に入れることはできません。
<!-- /内容モデル -->


<!-- a11y note -->
`main`要素のARIAロールは、要素名と同じ`main`です。スクリーンリーダーはこの要素に差し掛かると「メインランドマーク」のように読むことがあります。ランドマークとして機能するため、ランドマークにジャンプする機能で移動できます。
<!-- /a11y note -->
Expand Down
Loading

0 comments on commit f40cdab

Please sign in to comment.