Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 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の個性が反映されるようになりました。

前提知識の解説

このコミットの変更内容を理解するためには、以下の技術的な前提知識が必要です。

  1. Go Gopher: Go言語の公式マスコットであり、Renee Frenchによってデザインされました。GopherはGoコミュニティの象徴として広く使われており、Goの親しみやすいイメージを形成しています。このコミットでは、様々なポーズやテーマのGopher画像がドキュメントに追加されています。

  2. HTML (HyperText Markup Language): ウェブページの構造を定義するためのマークアップ言語です。

    • <img> タグ: 画像をウェブページに埋め込むために使用されます。src 属性で画像ファイルのパスを指定し、alt 属性で代替テキストを提供します。
    • class 属性: HTML要素に1つ以上のクラス名を割り当てます。これにより、CSSで特定のスタイルを適用したり、JavaScriptで要素を選択したりできます。
  3. CSS (Cascading Style Sheets): HTML要素の表示スタイル(色、フォント、レイアウトなど)を定義するためのスタイルシート言語です。

    • float プロパティ: 要素を左右のいずれかに浮動させ、テキストや他のインライン要素がその周りを回り込むように配置します。float: right; は要素を右に寄せます。
    • margin プロパティ: 要素の外側の余白を設定します。margin-left, margin-bottom などで特定の方向の余白を指定できます。
    • position プロパティ: 要素の配置方法を指定します。relative は要素を通常のドキュメントフロー内に配置しつつ、top, bottom, left, right プロパティで相対的な位置調整を可能にします。
    • top プロパティ: positionrelative または absolute の要素の、上端からのオフセットを指定します。
    • clear プロパティ: float プロパティが適用された要素の回り込みを解除します。clear: right; は、右に浮動した要素の隣に要素が回り込むのを防ぎ、その要素が浮動要素の下に配置されるようにします。これは、見出しなどがGopher画像の横に回り込まないようにするために重要です。
    • セレクタ: img.gophergopher クラスを持つ <img> 要素にスタイルを適用します。.pkgGopherpkgGopher クラスを持つ要素にスタイルを適用します。h2<h2> 要素にスタイルを適用します。
  4. GoDoc: Go言語のソースコードからドキュメンテーションを自動生成するツールです。GoDocは、Goのソースコード内のコメントや構造からHTMLドキュメントを生成し、Goの標準ライブラリやサードパーティライブラリのドキュメント表示に利用されます。lib/godoc/package.html は、GoDocがパッケージのドキュメントを生成する際に使用するHTMLテンプレートの一部です。

  5. Goテンプレートエンジン: Go言語には、HTMLやテキストを動的に生成するための組み込みテンプレートエンジンがあります。

    • {{with .Dirs}}: .Dirs が存在する場合にブロック内の処理を実行します。
    • {{if $.PDoc}}: $.PDoc(現在のコンテキストの PDoc フィールド)が真の場合にブロック内の処理を実行します。これにより、特定の条件に基づいてHTML要素の表示を切り替えることができます。

技術的詳細

このコミットは、Go言語のドキュメンテーションにおける視覚的な改善に焦点を当てています。主な変更点は以下の通りです。

  1. Gopher画像の追加: doc/gopher/ ディレクトリに、doc.png, help.png, pkg.png, project.png, run.png, talks.png といった新しいGopher画像ファイルが追加されました。これらはバイナリファイルとしてコミットされており、それぞれ特定のドキュメントセクションのテーマに合わせたデザインになっています。

  2. 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スタイルが適用されるようになりました。
  3. 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.gopherfloat: 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画像のレイアウトが崩れるのを防ぎ、ドキュメントの可読性を保ちます。

  4. 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画像が表示されます。この divimg には、前述の .pkgGopher および .pkgGopher .gopher CSSスタイルが適用され、Gopherが特定のレイアウトで表示されます。

この変更により、GoDocが生成するパッケージドキュメントの表示が、より視覚的に豊かになり、Goブランドの統一感が図られています。

関連リンク

参考にした情報源リンク