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

このコミットは、Go言語の公式ドキュメントツールであるgodocのウェブインターフェースにおけるスタイル変更と機能追加に関するものです。具体的には、リンクの表示スタイル変更、見出しレベルの調整、そしてGo Playgroundに「ポップアウト」ボタン（共有ボタン）の追加が行われました。

コミット

コミットハッシュ: e8636a64a2dd0f7c2821d97d5331d7a34e959ad5
作者: Andrew Gerrand adg@golang.org
日付: Tue Mar 13 11:00:11 2012 +1100

コミットメッセージ:

godoc: change link styles, add 'pop out' button

Remove underlines from all links, show underline on link hover.
Change all non-link headings to h4, a slight visual cue.

R=golang-dev, gri
CC=golang-dev
https://golang.org/cl/5783088

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

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

元コミット内容

godoc: change link styles, add 'pop out' button

Remove underlines from all links, show underline on link hover.
Change all non-link headings to h4, a slight visual cue.

R=golang-dev, gri
CC=golang-dev
https://golang.org/cl/5783088

変更の背景

このコミットは、Go言語のドキュメンテーションツールであるgodocのユーザーエクスペリエンスと視覚的な一貫性を向上させることを目的としています。当時のgodocは、Goコードのドキュメントを生成し、ウェブインターフェースを通じて提供する基本的なツールでした。

主な変更点は以下の通りです。

リンクスタイルの改善: 従来のリンクは常に下線が表示されていましたが、これを廃止し、マウスオーバー時（ホバー時）にのみ下線を表示するように変更されました。これは、よりモダンでクリーンなウェブデザインのトレンドに合わせたものであり、視覚的なノイズを減らし、コンテンツの可読性を向上させる効果があります。
見出しレベルの統一: リンクを含まない見出し（非リンク見出し）のHTML要素をh3からh4に変更することで、視覚的な階層を微調整し、ドキュメント全体の構造をより明確にしようとしています。これにより、ユーザーはコンテンツの重要度や関連性をより直感的に把握できるようになります。
Go Playgroundへの「ポップアウト」ボタン追加: Go Playgroundは、Goコードをブラウザ上で記述、コンパイル、実行できるインタラクティブな環境です。このコミットでは、Go Playgroundのコードスニペットを共有するための「ポップアウト」ボタン（実質的には「Share」ボタン）が追加されました。これにより、ユーザーは作成したコードを簡単に共有できるようになり、コラボレーションや学習体験が向上します。

これらの変更は、godocとGo Playgroundが提供する情報へのアクセス性を高め、ユーザーがGo言語の学習や開発をより快適に行えるようにするための細かな改善の一環です。

前提知識の解説

godoc

godocは、Go言語のソースコードからドキュメンテーションを生成するための公式ツールです。2012年当時、Go 1.0がリリースされたばかりの時期において、godocはGoコードのドキュメント化において非常に重要な役割を担っていました。

2012年時点のgodocの主な特徴:

ソースコード解析: godocはGoのソースコードとコメントを解析し、ドキュメントを生成します。
出力形式: HTML形式とプレーンテキスト形式の両方でドキュメントを出力できました。
ウェブインターフェース: godocはウェブインターフェースを提供し、ユーザーはドキュメントをブラウズしたり、関数のドキュメントから直接ソースコードの実装に移動したりすることができました。
シンプルな設計: PythonのDocstringやJavaのJavadocのような厳密な機械可読な構文を要求せず、コメントを「良いコメント」として扱いました。
ドキュメンテーション規約: 宣言（型、変数、定数、関数、パッケージ）の直前に空白行なしで配置されたコメントがドキュメントとして認識されました。パッケージコメントの最初の文はgodocのパッケージリストで使用され、より詳細な導入ドキュメントは専用のdoc.goファイルに記述できました。
HTMLの基本的な書式設定: コメントをHTMLに変換する際、空白行で段落を区切り、インデントされたテキストを整形済みテキストとしてレンダリングするなどの基本的な書式設定ルールに従いました。URLは自動的にHTMLリンクに変換されました。
非推奨のシグナル: 識別子が非推奨であることを示すために、「Deprecated:」で始まる段落をドキュメントコメントに追加できました。
アクセシビリティ: $GOROOT/src/pkgやGOPATHワークスペースにインストールされたGoパッケージにアクセスでき、コマンドラインとHTTPインターフェースの両方で利用可能でした。

Go Playground

Go Playgroundは、Go言語のコードをウェブブラウザ上で記述、コンパイル、実行できるインタラクティブなオンライン環境です。2010年3月にローンチされ、2012年時点でもGo言語の学習やコード共有に広く利用されていました。

2012年時点のGo Playgroundの主な特徴:

ウェブベースのコード実行: ユーザーはGoツールチェインをローカルにインストールすることなく、ウェブブラウザで直接Goコードを記述、コンパイル、実行できました。プログラムの出力やコンパイルエラーが返されました。
共有可能なURL: コードスニペットに対して一意の共有可能なURLを生成できる点が重要な機能でした。これにより、共同作業、学習、議論のためにコードを簡単に共有できました。
サンドボックス環境: コードはセキュアなサンドボックス環境で実行され、当初はGoogleのNative Client (NaCl) 技術を利用して、ユーザープログラムをホストシステムから隔離していました。
決定論的な出力: キャッシュを有効にし、再現可能な結果を保証するため、Playgroundは現在の時刻を「2009-11-10 23:00:00 UTC」に「凍結」していました。これにより、time.Now()のような関数は常にこの特定のタイムスタンプを返しました。
標準ライブラリのサポート（制限付き）: ほとんどのGo標準ライブラリが利用可能でしたが、セキュリティと整合性の理由から、直接システムコールを必要とするパッケージは制限されていました。
外部ネットワークアクセスなし: Playgroundで実行されるプログラムは、外部ネットワーク呼び出しを行うことができませんでした。
実行制限: リソースの乱用を防ぐため、実行時間、CPU使用率、メモリ消費量に制限が課されていました。
単一ファイル実行: ユーザーは通常、単一ファイル内でGoコードを記述することに制限されていました。
オプションのシンタックスハイライト: 2012年10月までに、シンタックスハイライトはユーザーが有効にできるオプション機能となっていました。

このコミットで追加された「ポップアウト」ボタンは、Go Playgroundの「共有可能なURL」機能と密接に関連しており、ユーザーがコードをより簡単に共有できるようにするためのUI改善です。

技術的詳細

このコミットは、主にHTML構造とCSSスタイルシートの変更、および新しい画像ファイルの追加によって、godocのウェブインターフェースの視覚的な側面とGo Playgroundの機能性を向上させています。

リンクの下線削除とホバー時の表示:
- doc/style.cssにおいて、a要素のtext-decoration: none;が追加され、デフォルトで下線が非表示になりました。
- a:hoverセレクタが追加され、text-decoration: underline;が設定されることで、マウスカーソルがリンク上にあるときにのみ下線が表示されるようになりました。
- 既存のh1 a, h2 a, h3 a, h4 aセレクタからtext-decoration: underline;が削除され、見出し内のリンクもこの新しいスタイルに従うようになりました。
- div#blog .title, div#video .titleセレクタからtext-decoration: none;が削除されましたが、これはおそらく冗長な指定の削除であり、新しいグローバルなリンクスタイルが適用されることを意味します。
見出しレベルの変更:
- doc/docs.htmlとdoc/reference.htmlにおいて、一部の<h3>タグが<h4>タグに変更されました。これは、リンクを含まない見出しの視覚的な重要度をわずかに下げることで、ドキュメントの階層構造をより細かく制御し、視覚的なヒントを提供することを目的としています。
Go Playgroundの「ポップアウト」ボタン追加:
- doc/share.pngという新しい画像ファイルが追加されました。これは、Go Playgroundの共有機能を表すアイコンとして使用されます。
- doc/root.htmlにおいて、Go Playgroundのセクション（<div id="learn">）内に<img class="icon share" src="/doc/share.png">が追加され、このアイコンが表示されるようになりました。
- Go Playgroundのコード入力エリア（<textarea>）と出力エリア（<pre>）のid属性が、より汎用的なclass属性に変更されました（例: id="code"からclass="code"）。
- 「Run」ボタンと「Share」ボタンのid属性もclass属性に変更されました（例: id="run"からclass="run"）。
- JavaScriptのplayground関数の初期化部分で、これらの要素を参照するためのセレクタが"#code"から"#learn .code"のように、より具体的なクラスセレクタに変更されました。これは、同じクラス名を持つ要素が複数存在する場合でも、特定のGo Playgroundセクション内の要素を正確にターゲットにするためです。
- doc/style.cssにdiv#learn .iconという新しいスタイルルールが追加され、Go Playground内のアイコン（share.png）が右側にフロートし、カーソルがポインターになるように設定されました。

これらの変更は、ユーザーインターフェースの美観と使いやすさを向上させるための、細部にわたる調整を示しています。

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

このコミットでは、以下の5つのファイルが変更されました。

doc/docs.html:
- 複数の<h3>タグが<h4>タグに変更されました。これは、ドキュメント内の見出しの階層を調整し、視覚的な一貫性を持たせるためです。
doc/reference.html:
- <h2>タグが<h4>タグに変更されました。これも見出しの階層調整の一環です。
doc/root.html:
- Go Playgroundセクションに共有アイコン（share.png）が追加されました。
- Go Playgroundのテキストエリア、出力エリア、およびボタンのid属性がclass属性に変更され、対応するJavaScriptのセレクタも更新されました。
doc/share.png:
- 新しいバイナリファイルとして追加されました。これはGo Playgroundの「ポップアウト」ボタンとして使用されるアイコン画像です。
doc/style.css:
- リンクのデフォルトの下線を削除し、ホバー時にのみ下線を表示するスタイルが追加されました。
- 見出し内のリンクの下線表示を削除するスタイルが変更されました。
- Go Playground内のアイコンのスタイル（フロート、カーソル）が追加されました。
- コードハイライトと選択範囲の背景色に関する微調整が行われました。

変更の概要: 24行の挿入、28行の削除。

コアとなるコードの解説

`doc/docs.html` および `doc/reference.html` の変更

これらのファイルでは、主にHTMLの見出しタグが変更されています。

例 (doc/docs.html):

--- a/doc/docs.html
+++ b/doc/docs.html
@@ -89,7 +89,7 @@ Go 1 matures.
 <p>The official blog of the Go project, featuring news and in-depth articles by
 the Go team and guests.</p>
 
-<h3>Codewalks</h3>
+<h4>Codewalks</h4>
 <p>
 Guided tours of Go programs. 
 </p>

これは、<h3>Codewalks</h3> が <h4>Codewalks</h4> に変更されたことを示しています。同様の変更が他の見出しにも適用されています。この変更は、ドキュメントのセクション構造における視覚的な階層を調整し、非リンク見出しの重要度をわずかに下げることで、全体的なレイアウトと可読性を向上させることを目的としています。

`doc/root.html` の変更

このファイルはGo PlaygroundのHTML構造を定義しており、共有機能の追加と要素の識別子変更が行われています。

共有アイコンの追加:

--- a/doc/root.html
+++ b/doc/root.html
@@ -5,9 +5,10 @@
 <div class="left">
 
 <div id="learn">
+<img class="icon share" src="/doc/share.png">
 <div class="rootHeading">Try Go</div>
 <div class="input">
-<textarea spellcheck="false" id="code">// You can edit this code!
+<textarea spellcheck="false" class="code">// You can edit this code!
 // Click here and start typing.
 package main

<img class="icon share" src="/doc/share.png"> が <div id="learn"> の直下に追加され、Go Playgroundのセクションに共有アイコンが表示されるようになりました。

IDからクラスへの変更とJavaScriptセレクタの更新:

--- a/doc/root.html
+++ b/doc/root.html
@@ -17,14 +18,14 @@ func main() {\n 	fmt.Println("Hello, 世界")\n }</textarea>\n </div>\n-<div class="output" id="output">\n+<div class="output">\n <pre>\n Hello, 世界\n </pre>\n </div>\n <div class="buttons">\n-<a id="run" href="#">Run</a>\n-<a id="share" href="#">Share</a>\n+<a class="run" href="#">Run</a>\n+<a class="share" href="#">Share</a>\n </div>\n </div>

id="code" が class="code" に、id="output" が class="output" に、id="run" が class="run" に、id="share" が class="share" に変更されています。

そして、JavaScript側でのこれらの要素の参照方法も変更されています。

--- a/doc/root.html
+++ b/doc/root.html
@@ -112,10 +113,10 @@ function init() {\n 	// Set up playground.\n 	playground({\n 		"simple":        true,\n-\t\t"codeEl":        "#code",\n-\t\t"outputEl":      "#output",\n-\t\t"runEl":         "#run",\n-\t\t"shareEl":       "#share",\n+\t\t"codeEl":        "#learn .code",\n+\t\t"outputEl":      "#learn .output",\n+\t\t"runEl":         "#learn .run",\n+\t\t"shareEl":       "#learn .share",\n \t\t"shareRedirect": "http://play.golang.org/p/"\n \t});\n }\n```

セレクタが `"#code"` のようなIDセレクタから `"#learn .code"` のようなクラスセレクタに変更されています。これは、より柔軟なCSSスタイリングと、同じクラス名を持つ複数の要素が存在する場合でも、特定のコンテキスト（`#learn` div内）の要素を正確にターゲットにするための変更です。

### `doc/share.png` の追加

このファイルはバイナリファイルとして追加されており、Go Playgroundの共有機能を表す視覚的なアイコンとして機能します。

### `doc/style.css` の変更

このファイルは、ウェブインターフェースの視覚的なスタイルを定義しています。

**リンクの下線スタイル変更:**

```diff
--- a/doc/style.css
+++ b/doc/style.css
@@ -34,6 +34,9 @@ a {\n 	color: #375EAB;\n 	text-decoration: none;\n }\n+a:hover {\n+\ttext-decoration: underline;\n+}\n p,\n pre,\n ul,\

a要素のtext-decorationがnoneに設定され、リンクのデフォルトの下線が削除されました。そして、a:hoverセレクタが追加され、ホバー時に下線が表示されるようになりました。

--- a/doc/style.css
+++ b/doc/style.css
@@ -82,13 +85,6 @@ h4 {\n 	margin: 0;\n }\n \n-h1 a,\n-h2 a,\n-h3 a,\n-h4 a {\n-\ttext-decoration: underline;\n-}\n-\

既存の見出し内のリンクに対する下線指定が削除され、新しいグローバルなリンクスタイルが適用されるようになりました。

Go Playgroundアイコンのスタイル:

--- a/doc/style.css
+++ b/doc/style.css
@@ -262,6 +258,10 @@ a#start .desc {\n \tmargin-top: 5px;\n }\n \n+div#learn .icon {\n+\tfloat: right;\n+\tcursor: pointer;\n+}\n div#learn pre,\n div#learn textarea {\n \tpadding: 0;\

div#learn .icon という新しいスタイルルールが追加され、Go Playground内のアイコンが右側にフロートし、カーソルがポインターになるように設定されています。これにより、アイコンがクリック可能であることを視覚的に示し、レイアウトを整えています。

これらの変更は、GoのドキュメンテーションとPlaygroundのウェブインターフェースのユーザーエクスペリエンスを向上させるための、細部にわたる配慮と実装を示しています。

comemo