[インデックス 10648] ファイルの概要

このコミットは、Go言語のドキュメンテーションツールであるgodocが生成するHTMLにおいて、<pre>タグが<p>タグの内部にネストされるというHTMLのセマンティクス上の問題を修正するものです。具体的には、lib/godoc/example.htmlとlib/godoc/package.htmlの2つのテンプレートファイルが変更され、不適切なHTML構造が是正されています。

コミット

commit e97a55810f4956f08a9738fa6a51dabdfece57c1
Author: Olivier Duperray <duperray.olivier@gmail.com>
Date:   Wed Dec 7 15:00:38 2011 -0500

    godoc: <pre> must not occur inside <p>
    Fixes #2532

    R=golang-dev, dr.volker.dobler, rsc
    CC=golang-dev
    https://golang.org/cl/5450115

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/e97a55810f4956f08a9738fa6a51dabdfece57c1

元コミット内容

godoc: <pre> must not occur inside <p> Fixes #2532

変更の背景

このコミットは、Go言語のドキュメンテーションツールであるgodocが生成するHTMLの構造に関する問題を修正するために行われました。具体的には、godocが生成するHTMLにおいて、整形済みテキストを表示するための<pre>タグが、段落を表す<p>タグの内部にネストされている箇所がありました。

HTMLの仕様では、<p>タグはフローコンテンツ（段落、画像、リンクなど）を含むことができますが、ブロックレベル要素（例: <div>, <h1>, <pre>など）を直接子要素として持つことはできません。<pre>タグはブロックレベル要素であり、その内容を整形済みテキストとして表示します。したがって、<p><pre>...</pre></p>のような構造はHTMLのセマンティクスに違反し、ブラウザによっては予期せぬレンダリング結果を引き起こしたり、HTMLバリデーションエラーの原因となったりする可能性があります。

この問題は、GoのIssueトラッカーで「Issue #2532」として報告されており、このコミットはその問題を解決することを目的としています。

前提知識の解説

HTMLの<p>タグと<pre>タグ

• <p>タグ (Paragraph Element):

  • HTMLにおける段落を表すブロックレベル要素です。
  • 通常、テキストやインライン要素（例: <a>, <strong>, <em>など）を含みます。
  • ブロックレベル要素を直接子要素として持つことはできません。ブラウザは通常、<p>タグ内にブロックレベル要素が出現すると、その<p>タグを自動的に閉じて新しいブロックを開始します。

• <pre>タグ (Preformatted Text Element):

  • HTMLにおける整形済みテキストを表すブロックレベル要素です。
  • このタグ内のテキストは、HTMLソースコードに記述された通りの空白（スペース、タブ、改行）を保持して表示されます。通常、等幅フォントでレンダリングされます。
  • 主にコードブロック、アスキーアート、または特定のフォーマットを維持する必要があるテキストの表示に使用されます。
  • ブロックレベル要素であるため、<p>タグの内部にネストされるべきではありません。

godoc

godocは、Go言語のソースコードからドキュメンテーションを生成するためのツールです。Goのソースコード内のコメント（特にエクスポートされた識別子に付随するコメント）を解析し、それらをHTML形式で整形して表示します。開発者はgodocを使用して、ローカルでGoの標準ライブラリや自身のプロジェクトのドキュメンテーションを閲覧できます。godocは、Goの公式ドキュメンテーションサイト (pkg.go.dev) の基盤としても使用されています。

godocは、Goのソースコードから抽出したドキュメンテーションコメントを、内部的にHTMLテンプレートを使用してレンダリングします。このコミットは、そのHTMLテンプレートの修正に関するものです。

技術的詳細

このコミットの技術的な詳細は、HTMLの構造的な整合性を保つことにあります。具体的には、godocが生成するHTMLにおいて、コード例や出力結果を表示する際に使用される<pre>タグが、誤って<p>タグの子要素として配置されていた問題を修正しています。

HTMLの仕様では、<p>要素は「フローコンテンツ」のみを含むことができ、その中にはブロックレベル要素（例: div, h1, preなど）は含まれません。<pre>要素はブロックレベル要素であるため、<p>要素の内部に配置することはセマンティクス的に誤りであり、HTMLのバリデーションエラーを引き起こす可能性があります。

このコミットでは、lib/godoc/example.htmlとlib/godoc/package.htmlという2つのHTMLテンプレートファイルが修正されています。これらのファイルでは、Goのテンプレートエンジン構文（{{.Code}}, {{html .Output}}, {{node_html .Decl $.FSet}}など）を使用して、動的にコンテンツが挿入されます。

修正前は、以下のような構造になっていました。

<p class="code"><pre>{{.Code}}</pre></p>
<p class="output"><pre>{{html .Output}}</pre></p>
<p><pre>{{node_html .Decl $.FSet}}</pre></p>

この構造では、<pre>タグが<p>タグの内部にネストされています。このコミットでは、<p>タグを削除し、<pre>タグを直接配置するように変更しています。これにより、HTMLのセマンティクスが正しくなり、ブラウザでのレンダリングの一貫性が向上します。

また、lib/godoc/package.htmlでは、<h4>Package files</h4>の前にあった<p>タグが削除され、<h4>タグの後に移動されています。これは、<h4>タグがブロックレベル要素であり、その前後に不要な<p>タグが存在しないようにするための調整と考えられます。

コアとなるコードの変更箇所

変更は以下の2つのファイルで行われています。

1. lib/godoc/example.html
2. lib/godoc/package.html

lib/godoc/example.html の変更

--- a/lib/godoc/example.html
+++ b/lib/godoc/example.html
@@ -5,10 +5,10 @@
  	<div class="expanded">\
  		<p class="exampleHeading">▾ Example</p>\
  		<p>Code:</p>\
-		<p class="code"><pre>{{.Code}}</pre></p>\
+		<pre class="code">{{.Code}}</pre>\
  		{{if .Output}}\
  		<p>Output:</p>\
-		<p class="output"><pre>{{html .Output}}</pre></p>\
+		<pre class="output">{{html .Output}}</pre>\
  		{{end}}\
  	</div>\
  </div>\

lib/godoc/package.html の変更

--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -51,8 +51,8 @@
  	{{comment_html .Doc}}\
  	{{if $.IsPkg}}\
  		{{with .Filenames}}\
-\t\t\t<p>\
  \t\t\t<h4>Package files</h4>\
+\t\t\t<p>\
  \t\t\t<span style=\"font-size:90%\">\
  \t\t\t{{range .}}\
  \t\t\t\t<a href=\"/{{.|srcLink}}\">{{.|filename|html}}</a>\
@@ -88,7 +88,7 @@
  \t\t{{$tname_html := node_html .Type.Name $.FSet}}\
  \t\t<h2 id=\"{{$tname_html}}\">type <a href=\"/{{posLink_url .Decl $.FSet}}\">{{$tname_html}}</a></h2>\
  \t\t{{comment_html .Doc}}\
-\t\t<p><pre>{{node_html .Decl $.FSet}}</pre></p>\
+\t\t<pre>{{node_html .Decl $.FSet}}</pre>\
  \t\t{{range .Consts}}\
  \t\t\t{{comment_html .Doc}}\
  \t\t\t<pre>{{node_html .Decl $.FSet}}</pre>\

コアとなるコードの解説

lib/godoc/example.html の変更点

このファイルは、Goのコード例（Example）の表示に使用されるテンプレートです。 変更前は、コードブロックと出力ブロックがそれぞれ<p class="code"><pre>...</pre></p>と<p class="output"><pre>...</pre></p>という形で記述されていました。 このコミットでは、これらの行がそれぞれ<pre class="code">...</pre>と<pre class="output">...</pre>に変更されています。 これにより、<pre>タグが直接HTMLドキュメントのフローに配置され、<p>タグの不適切なネストが解消されました。class="code"やclass="output"は<pre>タグに直接適用され、CSSによるスタイリングは引き続き機能します。

lib/godoc/package.html の変更点

このファイルは、Goのパッケージドキュメンテーションの表示に使用されるテンプレートです。

1. <h4>Package files</h4> 周りの変更: 変更前は<h4>Package files</h4>の前に不要な<p>タグがあり、その後に<span>タグが続いていました。 変更後、<h4>Package files</h4>の前の<p>タグが削除され、その後に新しい<p>タグが追加されています。これは、<h4>タグがブロックレベル要素であるため、その前後に余分な<p>タグが存在しないようにするための調整です。これにより、HTMLの構造がよりクリーンになります。

2. 型定義の表示部分の変更: 変更前は、型定義のコードブロックが<p><pre>{{node_html .Decl $.FSet}}</pre></p>という形で記述されていました。 このコミットでは、この行が<pre>{{node_html .Decl $.FSet}}</pre>に変更されています。 これもlib/godoc/example.htmlと同様に、<pre>タグの<p>タグ内への不適切なネストを解消するための修正です。これにより、型定義のコードブロックがHTMLのセマンティクスに沿って正しく表示されるようになります。

これらの変更は、godocが生成するHTMLがHTML標準に準拠し、より堅牢で互換性の高いものになることを保証します。

関連リンク

• Go CL: https://golang.org/cl/5450115
• GitHubコミットページ: https://github.com/golang/go/commit/e97a55810f4956f08a9738fa6a51dabdfece57c1

参考にした情報源リンク

• HTML <p> 要素: https://developer.mozilla.org/ja/docs/Web/HTML/Element/p
• HTML <pre> 要素: https://developer.mozilla.org/ja/docs/Web/HTML/Element/pre
• Go Doc Comments (Go 1.19以降の改善に関する情報): https://go.dev/blog/go1.19-doc (直接的なIssue #2532の解決策ではないが、godocのドキュメンテーションレンダリングに関する一般的な情報として参照)