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

このコミットは、Go言語のドキュメンテーションツールであるgodocの表示に関する修正です。具体的には、godocが生成するディレクトリ一覧において、パッケージ名が不適切に折り返される問題を解決しています。これにより、ディレクトリ一覧の視認性とレイアウトの一貫性が向上します。

コミット

commit f8dde60e2b70f6edccfec63980ef7e2b59fe9652
Author: Andrew Gerrand <adg@golang.org>
Date:   Fri Apr 20 10:04:13 2012 -0400

    doc: don't wrap package names in directory listing
    
    Fixes #3522.
    
    R=golang-dev, dsymonds
    CC=golang-dev
    https://golang.org/cl/6063054

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

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

元コミット内容

このコミットは、godocツールが生成するHTMLドキュメントのスタイルシートとテンプレートを修正し、ディレクトリ一覧におけるパッケージ名の表示を改善します。

具体的には、以下の変更が含まれます。

doc/style.css に新しいCSSルールを追加し、特定の条件下でテーブルセルの内容が折り返されないようにします。
lib/godoc/package.html のHTMLテンプレートを修正し、ディレクトリ一覧のパッケージ名を表示する<td>要素に新しいCSSクラスを適用します。

これにより、長いパッケージ名が複数行にわたって表示されることを防ぎ、レイアウトの崩れを修正します。

変更の背景

godocはGo言語のソースコードからドキュメントを生成し、Webブラウザで閲覧可能な形式で提供するツールです。このツールは、Goのパッケージやモジュールの構造を理解する上で非常に重要です。

以前のgodocのディレクトリ一覧表示では、長いパッケージ名がテーブルのセル内で自動的に折り返されてしまい、視覚的に不格好になったり、一覧全体のレイアウトが崩れたりする問題がありました。これは、CSSのword-wrap: break-word;プロパティが適用されているため、単語の途中で改行されてしまうことが原因でした。

このコミットは、この表示上の問題を解決し、ユーザーがgodocで生成されたドキュメントをより快適に閲覧できるようにすることを目的としています。コミットメッセージにあるFixes #3522は、この問題が内部の課題追跡システムで#3522として認識されていたことを示唆しています。

前提知識の解説

godoc

godocは、Go言語の公式ドキュメンテーションツールです。Goのソースコードに記述されたコメント（特にエクスポートされた識別子に対するコメント）を解析し、HTML形式のドキュメントを生成します。このドキュメントは、Goの標準ライブラリのドキュメント（pkg.go.dev）の基盤にもなっています。godocは、ローカルでGoのパッケージのドキュメントを閲覧する際にも利用されます。

HTMLテーブルとCSSのレイアウト

Webページでデータを表形式で表示するためにHTMLの<table>要素が使用されます。<table>は<tr>（行）と<td>（データセル）または<th>（ヘッダーセル）で構成されます。

CSS（Cascading Style Sheets）は、HTML要素の表示スタイルを定義するための言語です。このコミットでは、特に以下のCSSプロパティが重要です。

word-wrap: break-word;: このプロパティは、長い単語がコンテナの境界を越える場合に、単語の途中で改行することを許可します。これは、通常、長いURLやコードスニペットなどがレイアウトを崩すのを防ぐために使用されます。しかし、今回のケースではパッケージ名のような単語に対して意図しない改行を引き起こしていました。
white-space: nowrap;: このプロパティは、要素内のテキストが改行されないようにします。すべての空白文字は単一のスペースにまとめられ、テキストは可能な限り1行で表示されます。コンテナの幅を超えた場合は、通常、オーバーフローが発生します（例: テキストがはみ出す、スクロールバーが表示されるなど）。

Go言語には、html/templateパッケージがあり、Goのプログラム内でHTMLを動的に生成するための安全なテンプレートエンジンを提供します。このコミットで変更されているlib/godoc/package.htmlファイルは、このテンプレートエンジンで使用されるHTMLテンプレートの一部です。テンプレート内の{{...}}構文は、Goのテンプレートアクションを示し、データの挿入や条件分岐、ループ処理などを行います。

{{if $.DirFlat}}、{{if .HasPkg}}、{{else}}：条件分岐を制御します。
{{html .Path}}、{{html .Synopsis}}、{{html .Name}}：Goのテンプレート変数から値を取得し、HTMLエスケープ処理を施して出力します。これにより、クロスサイトスクリプティング（XSS）攻撃を防ぎます。
{{repeat .Depth}}：指定された文字列（ここでは非改行スペース）を.Depthの回数だけ繰り返します。これは、ディレクトリの階層構造をインデントで表現するために使用されます。

技術的詳細

このコミットの技術的な核心は、CSSのwhite-spaceプロパティを適切に適用することで、godocのディレクトリ一覧におけるパッケージ名の折り返しを制御することにあります。

doc/style.cssの変更: 既存のtable.dir tdルールにはword-wrap: break-word;が設定されており、これがパッケージ名の意図しない折り返しを引き起こしていました。このコミットでは、div#page.wide table.dir td.nameという新しいCSSセレクタが追加され、white-space: nowrap;が設定されています。
- div#page.wide: これは、ページ全体が広い表示モード（おそらくブラウザの幅が広い場合）であることを示すセレクタです。
- table.dir: ディレクトリ一覧を表示するテーブルに適用されるクラスです。
- td.name: 新たに導入されるCSSクラスで、パッケージ名を含むテーブルセルに適用されます。この新しいルールは、より特異性が高いため、既存のword-wrap: break-word;のルールを上書きし、パッケージ名が折り返されないようにします。
lib/godoc/package.htmlの変更: godocのHTMLテンプレートにおいて、ディレクトリ一覧の各行でパッケージ名を表示する<td>要素にclass="name"が追加されました。
- 変更前: <td class="name"><a href="{{html .Path}}">{{html .Path}}</a></td>
- 変更後: <td class="name"><a href=\"{{html .Path}}\">{{html .Path}}</a></td> この変更により、doc/style.cssで定義されたtd.nameセレクタがこの<td>要素に適用され、white-space: nowrap;のスタイルが有効になります。これにより、パッケージ名が1行で表示されるようになり、レイアウトの崩れが解消されます。

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

`doc/style.css`

--- a/doc/style.css
+++ b/doc/style.css
@@ -108,7 +108,9 @@ table.dir td {
 	word-wrap: break-word;
 	vertical-align: top;
 }
-
+div#page.wide table.dir td.name {
+	white-space: nowrap;
+}
 .alert {
 	color: #AA0000;
 }

`lib/godoc/package.html`

--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -192,14 +192,14 @@
 		{{if $.DirFlat}}
 			{{if .HasPkg}}
 				<tr>
-				<td><a href="{{html .Path}}">{{html .Path}}</a></td>
+				<td class="name"><a href="{{html .Path}}">{{html .Path}}</a></td>
 				<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
 				<td style="width: auto">{{html .Synopsis}}</td>
 				</tr>
 			{{end}}
 		{{else}}
 			<tr>
-			<td>{{repeat `&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;` .Depth}}<a href=\"{{html .Path}}\">{{html .Name}}</a></td>
+			<td class="name">{{repeat `&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;` .Depth}}<a href=\"{{html .Path}}\">{{html .Name}}</a></td>
 			<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
 			<td style="width: auto">{{html .Synopsis}}</td>
 			</tr>

コアとなるコードの解説

`doc/style.css`の変更解説

追加されたCSSルールは以下の通りです。

div#page.wide table.dir td.name {
	white-space: nowrap;
}

このルールは、div要素でid="page"とclass="wide"を持つ要素の子孫であるtable要素でclass="dir"を持つものの、さらにその子孫であるtd要素でclass="name"を持つものに対して適用されます。

white-space: nowrap;は、この<td>要素内のテキストが改行されないように強制します。これにより、長いパッケージ名も1行で表示され、テーブルのレイアウトが崩れるのを防ぎます。

`lib/godoc/package.html`の変更解説

package.htmlテンプレートでは、ディレクトリ一覧の各行を生成する部分で、パッケージ名やパスを表示する<td>要素にclass="name"が追加されています。

変更前:

<td><a href="{{html .Path}}">{{html .Path}}</a></td>

変更後:

<td class="name"><a href="{{html .Path}}">{{html .Path}}</a></td>

同様に、階層表示の場合も変更されています。