[インデックス 12404] ファイルの概要
このコミットは、Go言語の公式ドキュメンテーションサイトに、Goマスコットである「Gopher(ゴーファー)」の画像を複数追加し、それらの表示を制御するためのCSSスタイルを導入するものです。具体的には、ドキュメントの各セクション(貢献、ドキュメント、ヘルプ、参照など)に関連するGopher画像を埋め込み、視覚的な魅力を高め、ユーザーエクスペリエンスを向上させることを目的としています。また、GoDocツールが生成するパッケージドキュメントページにおいても、特定の条件下でGopher画像が表示されるように変更が加えられています。
コミット
commit f200b72a7c27a71b5d52da7d62e7ef16c2024f68
Author: Andrew Gerrand <adg@golang.org>
Date: Tue Mar 6 12:50:52 2012 +1100
doc: add more gophers
R=golang-dev, bradfitz, r
CC=golang-dev
https://golang.org/cl/5753047
GitHub上でのコミットページへのリンク
https://github.com/golang/go/commit/f200b72a7c27a71b5d52da7d62e7ef16c2024f68
元コミット内容
doc: add more gophers
R=golang-dev, bradfitz, r
CC=golang-dev
https://golang.org/cl/5753047
変更の背景
Go言語は、そのシンプルさ、効率性、並行処理のサポートにより、急速に人気を博しました。その魅力の一部は、愛らしいマスコットである「Go Gopher」にもあります。Gopherは、Goコミュニティの象徴として広く認識されており、公式ドキュメントやプロモーション資料に頻繁に登場します。
このコミットが行われた2012年3月は、Go言語がまだ比較的新しい時期であり、Go 1のリリースが間近に迫っていました。この時期において、ドキュメンテーションの質と視覚的な魅力は、新しいユーザーを引きつけ、コミュニティのアイデンティティを確立する上で非常に重要でした。
このコミットの背景には、Goのドキュメンテーションをより親しみやすく、視覚的に魅力的なものにするという意図があります。各ドキュメントセクションにテーマに沿ったGopher画像を配置することで、ユーザーはより楽しく情報を探索でき、Goブランドの認知度向上にも寄与します。特に、GoDocによって自動生成されるパッケージドキュメントにもGopherが追加されることで、開発者が日常的に参照する情報源にもGoの個性が反映されるようになりました。
前提知識の解説
このコミットの変更内容を理解するためには、以下の技術的な前提知識が必要です。
-
Go Gopher: Go言語の公式マスコットであり、Renee Frenchによってデザインされました。GopherはGoコミュニティの象徴として広く使われており、Goの親しみやすいイメージを形成しています。このコミットでは、様々なポーズやテーマのGopher画像がドキュメントに追加されています。
-
HTML (HyperText Markup Language): ウェブページの構造を定義するためのマークアップ言語です。
<img>
タグ: 画像をウェブページに埋め込むために使用されます。src
属性で画像ファイルのパスを指定し、alt
属性で代替テキストを提供します。class
属性: HTML要素に1つ以上のクラス名を割り当てます。これにより、CSSで特定のスタイルを適用したり、JavaScriptで要素を選択したりできます。
-
CSS (Cascading Style Sheets): HTML要素の表示スタイル(色、フォント、レイアウトなど)を定義するためのスタイルシート言語です。
float
プロパティ: 要素を左右のいずれかに浮動させ、テキストや他のインライン要素がその周りを回り込むように配置します。float: right;
は要素を右に寄せます。margin
プロパティ: 要素の外側の余白を設定します。margin-left
,margin-bottom
などで特定の方向の余白を指定できます。position
プロパティ: 要素の配置方法を指定します。relative
は要素を通常のドキュメントフロー内に配置しつつ、top
,bottom
,left
,right
プロパティで相対的な位置調整を可能にします。top
プロパティ:position
がrelative
またはabsolute
の要素の、上端からのオフセットを指定します。clear
プロパティ:float
プロパティが適用された要素の回り込みを解除します。clear: right;
は、右に浮動した要素の隣に要素が回り込むのを防ぎ、その要素が浮動要素の下に配置されるようにします。これは、見出しなどがGopher画像の横に回り込まないようにするために重要です。- セレクタ:
img.gopher
はgopher
クラスを持つ<img>
要素にスタイルを適用します。.pkgGopher
はpkgGopher
クラスを持つ要素にスタイルを適用します。h2
は<h2>
要素にスタイルを適用します。
-
GoDoc: Go言語のソースコードからドキュメンテーションを自動生成するツールです。GoDocは、Goのソースコード内のコメントや構造からHTMLドキュメントを生成し、Goの標準ライブラリやサードパーティライブラリのドキュメント表示に利用されます。
lib/godoc/package.html
は、GoDocがパッケージのドキュメントを生成する際に使用するHTMLテンプレートの一部です。 -
Goテンプレートエンジン: Go言語には、HTMLやテキストを動的に生成するための組み込みテンプレートエンジンがあります。
{{with .Dirs}}
:.Dirs
が存在する場合にブロック内の処理を実行します。{{if $.PDoc}}
:$.PDoc
(現在のコンテキストのPDoc
フィールド)が真の場合にブロック内の処理を実行します。これにより、特定の条件に基づいてHTML要素の表示を切り替えることができます。
技術的詳細
このコミットは、Go言語のドキュメンテーションにおける視覚的な改善に焦点を当てています。主な変更点は以下の通りです。
-
Gopher画像の追加:
doc/gopher/
ディレクトリに、doc.png
,help.png
,pkg.png
,project.png
,run.png
,talks.png
といった新しいGopher画像ファイルが追加されました。これらはバイナリファイルとしてコミットされており、それぞれ特定のドキュメントセクションのテーマに合わせたデザインになっています。 -
HTMLドキュメントへのGopher画像の埋め込み:
doc/contrib.html
(貢献ページ):<img class="gopher" src="/doc/gopher/project.png" />
が追加され、プロジェクト関連のGopherが表示されます。doc/docs.html
(ドキュメント一覧ページ): 「Learning Go」セクションにdoc.png
、「Talks」セクションにtalks.png
、「The Go Community」セクションにproject.png
がそれぞれ追加されました。doc/help.html
(ヘルプページ):<img class="gopher" src="/doc/gopher/help.png" />
が追加され、ヘルプ関連のGopherが表示されます。doc/reference.html
(参照ページ): 既存のGopher画像 (ref.png
) にclass="gopher"
が追加され、新しいCSSスタイルが適用されるようになりました。
-
Gopher画像表示のためのCSSスタイルの追加:
doc/style.css
に以下の新しいCSSルールが追加されました。-
img.gopher
:img.gopher { float: right; margin-left: 10px; margin-bottom: 10px; }
このスタイルは、
gopher
クラスを持つすべての<img>
要素に適用されます。画像を右に浮動させ、左と下部に10pxの余白を持たせることで、テキストが画像の左側と上側を回り込むように配置されます。これにより、ドキュメントのレイアウトが整理され、Gopher画像がコンテンツの邪魔をせず、かつ視覚的なアクセントとなるように設計されています。 -
.pkgGopher
およびその子要素のスタイル:.pkgGopher { text-align: right; } .pkgGopher .gopher { float: none; position: relative; top: -40px; margin-bottom: -120px; }
これらのスタイルは、GoDocが生成するパッケージドキュメント (
lib/godoc/package.html
で使用) におけるGopher画像の特殊な配置を目的としています。.pkgGopher
は、その中のコンテンツを右寄せにします。.pkgGopher .gopher
は、通常のimg.gopher
のfloat: right;
をfloat: none;
で解除し、position: relative;
とtop: -40px;
で上方向に40pxずらします。また、margin-bottom: -120px;
で負のマージンを設定することで、画像が占める垂直方向のスペースを縮小し、後続のコンテンツが画像の下に大きく食い込むように調整されています。これは、パッケージのサブディレクトリリストの隣にGopherを配置しつつ、リストの開始位置をあまり下げないようにするための工夫と考えられます。
-
h2 { clear: right; }
:h2 { clear: right; }
このルールは、すべての
<h2>
見出しに適用されます。clear: right;
を指定することで、float: right;
が適用されたGopher画像の右側に<h2>
見出しが回り込むのを防ぎ、必ずGopher画像の下に配置されるようにします。これにより、見出しとGopher画像のレイアウトが崩れるのを防ぎ、ドキュメントの可読性を保ちます。
-
-
GoDocテンプレートの変更:
lib/godoc/package.html
では、パッケージのサブディレクトリリストの表示に関する条件分岐が変更されました。 以前は{{if $.PDoc}}<h2 id="subdirectories">Subdirectories</h2>{{end}}
であった部分が、以下のように拡張されました。{{if $.PDoc}} <h2 id="subdirectories">Subdirectories</h2> {{else}} <div class="pkgGopher"> <img class="gopher" src="/doc/gopher/pkg.png"/> </div> {{end}}
この変更により、
$.PDoc
が真(おそらくパッケージの概要ページなど、特定のドキュメントタイプ)の場合には通常通り「Subdirectories」の見出しが表示され、そうでない場合(例えば、パッケージのルートページでサブディレクトリが存在しない場合など)には、pkgGopher
クラスを持つdiv
内にpkg.png
のGopher画像が表示されるようになりました。これにより、GoDocが生成するパッケージドキュメントにもGopherが組み込まれ、統一された視覚体験が提供されます。
これらの変更は、Go言語のドキュメンテーションをより魅力的で、ユーザーフレンドリーなものにするための細やかな配慮がなされていることを示しています。
コアとなるコードの変更箇所
doc/contrib.html
(および他のHTMLファイル) への画像追加
--- a/doc/contrib.html
+++ b/doc/contrib.html
@@ -3,6 +3,8 @@
"Path": "/project/"
}-->
+<img class="gopher" src="/doc/gopher/project.png" />
+
<div id="manual-nav"></div>
<p>
doc/style.css
へのGopher関連CSSの追加
--- a/doc/style.css
+++ b/doc/style.css
@@ -367,3 +367,20 @@ div#blog .read {
table.codetable { margin-left: auto; margin-right: auto; border-style: none; }
hr { border-style: none; border-top: 1px solid black; }
+
+img.gopher {
+ float: right;
+ margin-left: 10px;
+ margin-bottom: 10px;
+}
+.pkgGopher {
+ text-align: right;
+}
+.pkgGopher .gopher {
+ float: none;
+ position: relative;
+ top: -40px;
+ margin-bottom: -120px;
+}
+h2 { clear: right; }
+
lib/godoc/package.html
の条件付き画像表示ロジックの変更
--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -163,7 +163,13 @@
{{with .Dirs}}
{{/* DirList entries are numbers and strings - no need for FSet */}}
- {{if $.PDoc}}<h2 id="subdirectories">Subdirectories</h2>{{end}}
+ {{if $.PDoc}}
+ <h2 id="subdirectories">Subdirectories</h2>
+ {{else}}
+ <div class="pkgGopher">
+ <img class="gopher" src="/doc/gopher/pkg.png"/>
+ </div>
+ {{end}}
<table class="dir">
<tr>
<th>Name</th>
コアとなるコードの解説
HTMLファイルへの画像追加 (doc/contrib.html
の例)
<img class="gopher" src="/doc/gopher/project.png" />
この行は、project.png
というGopher画像をHTMLドキュメントに埋め込んでいます。src
属性は画像のパスを指定し、/doc/gopher/project.png
はGoのドキュメンテーションサイトのルートからの相対パスを示しています。class="gopher"
は、この画像に後述するCSSルール .gopher
を適用するためのものです。これにより、画像は右に浮動し、周囲のテキストとの間に適切な余白が確保されます。
CSSスタイル (doc/style.css
)
img.gopher
img.gopher {
float: right;
margin-left: 10px;
margin-bottom: 10px;
}
このCSSルールは、gopher
クラスを持つすべての <img>
要素に適用されます。
float: right;
: 画像を親要素の右端に寄せ、後続のコンテンツが画像の左側を回り込むように配置します。margin-left: 10px;
: 画像の左側に10ピクセルの余白を追加し、画像と左側のテキストとの間にスペースを設けます。margin-bottom: 10px;
: 画像の下側に10ピクセルの余白を追加し、画像と下側のコンテンツとの間にスペースを設けます。 これらのプロパティにより、Gopher画像はドキュメントの右上に配置され、テキストの邪魔をせず、かつ視覚的なアクセントとして機能します。
.pkgGopher
と .pkgGopher .gopher
.pkgGopher {
text-align: right;
}
.pkgGopher .gopher {
float: none;
position: relative;
top: -40px;
margin-bottom: -120px;
}
これらのスタイルは、GoDocが生成するパッケージドキュメント内で pkg.png
Gopherを特殊な方法で配置するために使用されます。
.pkgGopher
: このクラスを持つ要素内のインラインコンテンツ(この場合は画像)を右寄せにします。.pkgGopher .gopher
:.pkgGopher
の子孫であるgopher
クラスを持つ<img>
要素に適用されます。float: none;
: 通常のimg.gopher
に適用されるfloat: right;
を解除し、要素を通常のドキュメントフローに戻します。position: relative;
: 要素を通常のフロー内に配置しつつ、top
,bottom
,left
,right
プロパティによる相対的な位置調整を可能にします。top: -40px;
: 要素を通常の位置から上方向に40ピクセル移動させます。margin-bottom: -120px;
: 要素の下側に負のマージンを適用します。これにより、要素が占める垂直方向のスペースが縮小され、後続のコンテンツが画像の下に大きく食い込むように配置されます。これは、パッケージのサブディレクトリリストの隣にGopherを配置しつつ、リストの開始位置をあまり下げないようにするための、高度なレイアウト調整です。
h2
h2 { clear: right; }
このルールは、すべての <h2>
見出しに適用されます。
clear: right;
: 右に浮動している要素(この場合はGopher画像)の隣に<h2>
見出しが回り込むのを防ぎます。これにより、<h2>
見出しは必ず浮動要素の下に配置され、ドキュメントの構造と可読性が保たれます。
GoDocテンプレートの変更 (lib/godoc/package.html
)
{{if $.PDoc}}
<h2 id="subdirectories">Subdirectories</h2>
{{else}}
<div class="pkgGopher">
<img class="gopher" src="/doc/gopher/pkg.png"/>
</div>
{{end}}
このGoテンプレートのコードは、GoDocがパッケージドキュメントを生成する際の条件分岐を定義しています。
{{if $.PDoc}}
:$.PDoc
という変数が真(true)であるかどうかをチェックします。PDoc
はおそらく「Package Document」のような意味で、特定の種類のパッケージドキュメントページで真となるフラグと考えられます。- 真の場合:
<h2 id="subdirectories">Subdirectories</h2>
が出力され、通常の「Subdirectories」見出しが表示されます。
- 真の場合:
{{else}}
:$.PDoc
が偽(false)の場合に実行されます。- 偽の場合:
<div class="pkgGopher">
で囲まれたpkg.png
のGopher画像が表示されます。このdiv
とimg
には、前述の.pkgGopher
および.pkgGopher .gopher
CSSスタイルが適用され、Gopherが特定のレイアウトで表示されます。
- 偽の場合:
この変更により、GoDocが生成するパッケージドキュメントの表示が、より視覚的に豊かになり、Goブランドの統一感が図られています。
関連リンク
- Go言語公式サイト: https://go.dev/
- Go Gopherについて (Go Wiki): https://go.dev/wiki/GoGopher
- A Tour of Go: https://tour.golang.org/ (このコミットで画像が追加された
doc/docs.html
からリンクされている)
参考にした情報源リンク
- Git diff: コミットに含まれる差分情報
- HTML
<img>
タグ: https://developer.mozilla.org/ja/docs/Web/HTML/Element/img - CSS
float
プロパティ: https://developer.mozilla.org/ja/docs/Web/CSS/float - CSS
margin
プロパティ: https://developer.mozilla.org/ja/docs/Web/CSS/margin - CSS
position
プロパティ: https://developer.mozilla.org/ja/docs/Web/CSS/position - CSS
clear
プロパティ: https://developer.mozilla.org/ja/docs/Web/CSS/clear - GoDoc: https://go.dev/blog/godoc
- Go text/templateパッケージ: https://pkg.go.dev/text/template
- Go html/templateパッケージ: https://pkg.go.dev/html/template