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

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

このコミットは、Go言語の公式ドキュメントの一部である doc/reference.html ファイルにおいて、サブリポジトリに関するセクションの表示位置を変更するものです。具体的には、「Sub-repositories」の見出しとその内容を、ページのより下部に移動させることで、ドキュメントの論理的な流れと視認性を改善することを目的としています。

コミット

  • コミットハッシュ: 6230569e841543a68b3a68c96f8856b6180199b4
  • 作者: Andrew Gerrand adg@golang.org
  • コミット日時: Mon Mar 19 13:52:26 2012 +1100
  • コミットメッセージ: 
    doc: move sub-repos lower on reference page

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5846065

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

https://github.com/golang/go/commit/6230569e841543a68b3a68c96f8856b6180199b4

元コミット内容

doc: move sub-repos lower on reference page

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5846065

変更の背景

この変更の背景には、doc/reference.html というGo言語の参照ドキュメントの構成と、ユーザーが情報を探す際の利便性の向上が挙げられます。元の配置では、サブリポジトリに関する情報がページの比較的上部に位置していましたが、これはGo言語のコアな参照情報（コマンドドキュメントや言語仕様など）よりも優先度が高いとは考えられていなかった可能性があります。

ドキュメントの読者が最初に目にするべき情報や、より頻繁に参照されるであろう情報がページの冒頭に配置されるべきという考えに基づき、サブリポジトリのような特定のトピックに関する情報は、より一般的な情報や基本的な説明の後に続くように再配置されたと推測されます。これにより、ドキュメント全体の論理的な流れが改善され、ユーザーが目的の情報をより効率的に見つけられるようになることが期待されます。

前提知識の解説

このコミットを理解するためには、以下の前提知識が役立ちます。

  1. Go言語のドキュメント構造: Go言語の公式ドキュメントは、golang.org で公開されており、言語仕様、標準ライブラリ、コマンド、ツール、記事など、多岐にわたる情報を提供しています。doc/reference.html は、これらのドキュメント群の一部であり、Go言語に関する様々な参照情報がまとめられているページです。

  2. Go言語のサブリポジトリ (Sub-repositories): Go言語のエコシステムには、メインのGoツリー（標準ライブラリなど）とは別に、「サブリポジトリ」と呼ばれるプロジェクト群が存在します。これらはGoプロジェクトの一部ではありますが、メインのGoツリーとは異なる、より緩やかな互換性要件（go1compat.html で説明されている）の下で開発されています。これらは通常、go get コマンドを使用してインストールされ、例えば code.google.com/p/go.crypto や code.google.com/p/go.net のように、特定の機能（暗号化、ネットワーク関連など）を提供します。これらはGo言語のコア機能ではないが、Goプロジェクトによって公式に管理されている拡張機能と考えることができます。

  3. HTMLの構造: doc/reference.html はHTMLファイルであり、ウェブページの構造を定義しています。このコミットでは、HTMLの <h4 id="subrepos"> 見出しと、それに続く <p> タグ（段落）および <ul> タグ（順序なしリスト）で構成されるセクションが移動されています。HTMLの id 属性は、特定の要素を一意に識別するために使用され、ページ内リンク（アンカーリンク）のターゲットとしても機能します。

  4. go get コマンド: Go言語のパッケージ管理ツールであり、リモートリポジトリからGoパッケージとその依存関係をダウンロードし、インストールするために使用されます。サブリポジトリもこのコマンドで取得されます。

技術的詳細

このコミットは、doc/reference.html ファイル内のHTML構造を直接変更しています。具体的には、以下のHTMLブロックが移動されています。

<h4 id="subrepos">Sub-repositories</h4>

<p>
These packages are part of the Go Project but outside the main Go tree.
They are developed under looser <a href="/doc/go1compat.html">compatibility
requirements</a> than the Go core.
Install them with "<code><a href="/cmd/go/#Download_and_install_packages_and_dependencies">go get</a></code>".
</p>

<ul>
<li><a href="http://code.google.com/p/go/source/browse?repo=codereview"><code>code.google.com/p/go.codereview</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.codereview">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=crypto"><code>code.google.com/p/go.crypto</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.crypto">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=image"><code>code.google.com/p/go.image</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.image">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=net"><code>code.google.com/p/go.net</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.net/docs">docs</a>]
</ul>

このブロックは、ファイルの冒頭近くにあった <h4 id="subrepos"> から始まるセクション全体を、ページのより下部にある <h4 id="articles"> の直前に移動させています。

変更の技術的な影響は以下の通りです。

  • HTML構造の変更: ページのDOMツリーにおける要素の順序が変更されます。
  • 表示順序の変更: ウェブブラウザでページが表示された際に、「Sub-repositories」セクションが以前よりも下部に表示されるようになります。
  • ページ内リンクの維持: id="subrepos" というアンカーは維持されているため、このセクションへの既存のページ内リンク（例: doc/reference.html#subrepos）は引き続き機能します。
  • CSS/JavaScriptへの影響: 純粋なHTML要素の移動であるため、この変更自体が既存のCSSスタイルやJavaScriptの動作に直接的な影響を与える可能性は低いですが、もしCSSセレクタやJavaScriptが要素の特定の順序や親要素に依存している場合は、間接的な影響が生じる可能性もゼロではありません。しかし、このケースではその可能性は低いと考えられます。

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

--- a/doc/reference.html
+++ b/doc/reference.html
@@ -14,22 +14,6 @@
 The documentation for the Go standard library.
 </p>
 
-<h4 id=\"subrepos\">Sub-repositories</h4>
-
-<p>
-These packages are part of the Go Project but outside the main Go tree.
-They are developed under looser <a href=\"/doc/go1compat.html\">compatibility
-requirements</a> than the Go core.
-Install them with \"<code><a href=\"/cmd/go/#Download_and_install_packages_and_dependencies\">go get</a></code>\".
-</p>
-
-<ul>
-<li><a href=\"http://code.google.com/p/go/source/browse?repo=codereview\"><code>code.google.com/p/go.codereview</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.codereview\">docs</a>]
-<li><a href=\"http://code.google.com/p/go/source/browse?repo=crypto\"><code>code.google.com/p/go.crypto</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.crypto\">docs</a>]
-<li><a href=\"http://code.google.com/p/go/source/browse?repo=image\"><code>code.google.com/p/go.image</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.image\">docs</a>]
-<li><a href=\"http://code.google.com/p/go/source/browse?repo=net\"><code>code.google.com/p/go.net</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.net\">docs</a>]
-</ul>
-
 <h3 id=\"cmd\"><a href=\"/ref/cmd\">Command Documentation</a></h3>
 <p>
 The documentation for the Go tools.\n@@ -58,6 +42,22 @@ same variable in a different goroutine.\n Using GDB to debug Go programs.\n </p>\n \n+<h4 id=\"subrepos\">Sub-repositories</h4>\n+\n+<p>\n+These packages are part of the Go Project but outside the main Go tree.\n+They are developed under looser <a href=\"/doc/go1compat.html\">compatibility\n+requirements</a> than the Go core.\n+Install them with \"<code><a href=\"/cmd/go/#Download_and_install_packages_and_dependencies\">go get</a></code>\".\n+</p>\n+\n+<ul>\n+<li><a href=\"http://code.google.com/p/go/source/browse?repo=codereview\"><code>code.google.com/p/go.codereview</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.codereview\">docs</a>]\n+<li><a href=\"http://code.google.com/p/go/source/browse?repo=crypto\"><code>code.google.com/p/go.crypto</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.crypto\">docs</a>]\n+<li><a href=\"http://code.google.com/p/go/source/browse?repo=image\"><code>code.google.com/p/go.image</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.image\">docs</a>]\n+<li><a href=\"http://code.google.com/p/go/source/browse?repo=net\"><code>code.google.com/p/go.net</code></a> [<a href=\"http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.net\">docs</a>]\n+</ul>\n+\n <h4 id=\"articles\">Articles</h4>
 
 <ul>

コアとなるコードの解説

上記の差分は、doc/reference.html ファイルに対する変更を示しています。

  • - で始まる行: これらは元のファイルから削除された行を示します。このコミットでは、ファイルの行14から行35にかけて存在していた「Sub-repositories」セクション全体（<h4 id="subrepos"> から </ul> まで）が削除されています。このセクションは、サブリポジトリの概要と、code.google.com/p/go.codereview、go.crypto、go.image、go.net といった具体的なサブリポジトリへのリンクを含んでいました。

  • + で始まる行: これらは新しいファイルに追加された行を示します。このコミットでは、ファイルの行58の後に、削除されたものと全く同じ「Sub-repositories」セクションが追加されています。追加された位置は、既存の <h4 id="articles">Articles</h4> 見出しの直前です。

この変更は、実質的に「Sub-repositories」セクションをファイル内の異なる位置に「移動」させたことを意味します。コンテンツ自体は変更されておらず、単にその表示順序が変更されただけです。これにより、Go言語の参照ドキュメントにおける情報の提示順序が調整され、読者にとってより自然な情報の流れが提供されることを意図しています。

関連リンク

  • Go Change List (CL): このコミットに関連するGoのコードレビューシステム上の変更リストです。詳細な議論やレビューコメントが含まれている場合があります。 https://golang.org/cl/5846065

参考にした情報源リンク