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

コミット

commit 01156f05de8b3a54b37458dfa4b71dacc43d0c72
Author: Andrew Gerrand <adg@golang.org>
Date:   Tue Feb 21 14:12:07 2012 +1100

    doc: fix links in installation instructions
    
    Fixes #3051.
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/5683056

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

https://github.com/golang/go/commit/01156f05de8b3a54b37458dfa4b71dacc43d0c72

このコミットは、Go言語の公式ドキュメント内のインストール手順に関するリンクを修正することを目的としています。具体的には、doc: fix links in installation instructions という簡潔なメッセージが示しており、ドキュメント内のリンクが正しく機能していなかった問題を解決しようとしています。Fixes #3051. という記述から、この変更がGoプロジェクトのIssue 3051を修正するものであることがわかります。

変更の背景

このコミットの背景には、Go言語の公式ドキュメント、特にインストール手順に関するページにおいて、内部リンクが正しく機能していなかったという問題があります。ユーザーがGoをインストールする際に参照する重要なドキュメント内でリンク切れが発生していると、ユーザー体験が著しく損なわれ、必要な情報にたどり着けない可能性があります。

Fixes #3051 という記述は、このコミットがGoプロジェクトのIssueトラッカーで報告された特定のバグ（Issue 3051）を解決するために行われたことを示しています。通常、このようなIssueは、ユーザーからの報告や開発者自身による発見によって、ドキュメントの不備が明らかになった場合に作成されます。この場合、相対パスで記述されていたリンクが、特定のコンテキスト（例えば、ドキュメントがホストされているWebサーバーのルートパスや、異なるディレクトリ構造）で正しく解決されず、リンク切れを引き起こしていたと考えられます。

この修正は、Go言語のドキュメントの品質とユーザーの利便性を向上させるための、保守的な変更と言えます。

前提知識の解説

1. HTMLにおける相対パスと絶対パス

Webページにおけるリンク（<a>タグのhref属性）の指定方法には、大きく分けて「相対パス」と「絶対パス」の2種類があります。

相対パス (Relative Path): 現在のファイルの位置を基準にして、目的のファイルへのパスを指定する方法です。例えば、./images/photo.jpg は現在のディレクトリ内の images フォルダにある photo.jpg を指します。../index.html は一つ上のディレクトリにある index.html を指します。相対パスは、ファイル間の関係性が明確で、サイト全体のディレクトリ構造が変更されても、相対的な位置関係が変わらなければリンクを修正する必要がないという利点があります。しかし、現在のページのURLやディレクトリ構造によってリンクの解決方法が変わるため、意図しないリンク切れが発生するリスクもあります。
絶対パス (Absolute Path): ドキュメントルート（Webサイトの最上位ディレクトリ）またはプロトコルとドメイン名を含む完全なURLを基準にして、目的のファイルへのパスを指定する方法です。
- ルート相対パス: /doc/go_tutorial.html のように、ドメインのルート (/) から始まるパスです。これは、Webサイトのドキュメントルートを基準とします。例えば、https://example.com/ がドキュメントルートであれば、/doc/go_tutorial.html は https://example.com/doc/go_tutorial.html を指します。
- 完全なURL: https://www.google.com/ のように、プロトコル（http:// や https://）、ドメイン名、ポート番号、パスなど、すべての情報を含む形式です。

このコミットでは、相対パスで記述されていた内部リンクを、ルート相対パス（/doc/ や /install/ から始まるパス）に修正しています。これにより、ドキュメントがどのURLパスからアクセスされても、常にWebサイトのルートを基準として正しいリソースにリンクされるようになります。

2. Go言語のドキュメント構造

Go言語の公式ドキュメントは、通常、golang.org ドメインの下にホストされています。ドキュメントの多くは /doc/ パス以下に配置されており、例えばチュートリアルは /doc/go_tutorial.html、Effective Goは /doc/effective_go.html といった形式でアクセスされます。インストール関連のドキュメントは /install/ 以下に配置されることもあります。

この構造を理解することで、なぜ相対パスが問題となり、ルート相対パスへの変更が適切であったかが明確になります。

3. Gerrit Change-ID (`golang.org/cl/`)

コミットメッセージにある https://golang.org/cl/5683056 は、Goプロジェクトがコードレビューに利用しているGerritというシステムにおける変更セット（Change-ID）へのリンクです。Gerritは、Gitリポジトリに対する変更をレビューし、承認するためのWebベースのツールです。開発者は変更をGerritにアップロードし、他の開発者からのレビューを経て、最終的にリポジトリにマージされます。このリンクは、このコミットがGerrit上でどのようにレビューされ、議論されたかの履歴を追跡するために使用されます。

技術的詳細

このコミットの技術的な詳細は、HTMLファイル内の<a>タグのhref属性値の変更に集約されます。具体的には、以下の2つのファイルが修正されています。

doc/install-source.html
doc/install.html

これらのファイル内で、Go言語の様々なドキュメントやツールへのリンクが、相対パスからルート相対パスへと変更されています。

変更のパターン:

gccgo_install.html → /install/gccgo/
go_tutorial.html → /doc/go_tutorial.html
codelab/wiki/ → /doc/codelab/wiki/
effective_go.html → /doc/effective_go.html
docs.html → /doc/

この変更により、例えば doc/install-source.html が /doc/install-source.html というURLでアクセスされた場合でも、そのページから /doc/go_tutorial.html へのリンクは常に golang.org/doc/go_tutorial.html を指すようになります。もし相対パスの go_tutorial.html のままであった場合、ブラウザは現在のURL (/doc/install-source.html) を基準に doc/go_tutorial.html を解決しようとし、結果として golang.org/doc/doc/go_tutorial.html のような誤ったURLを生成してしまう可能性がありました。

ルート相対パスを使用することで、ドキュメントの配置場所や、Webサーバーがドキュメントをどのように提供しているかに関わらず、リンクが常にWebサイトのルートからの絶対的な位置を指すため、リンク切れのリスクを大幅に低減できます。これは、特に大規模なWebサイトや、ドキュメントのURL構造が変更される可能性がある場合に推奨されるプラクティスです。

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

このコミットでは、以下の2つのHTMLファイルが変更されています。

doc/install-source.html
doc/install.html

それぞれのファイルで、既存の相対パスのリンクが、Webサイトのルートからの絶対パス（/doc/ や /install/ から始まるパス）に修正されています。

コアとなるコードの解説

以下に、変更されたファイルの差分（diff）を示し、それぞれの変更が何を意味するのかを解説します。

--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -19,7 +19,7 @@ This document focuses on the <code>gc</code> Go
 compiler and tools (<code>6g</code>, <code>8g</code> etc.).
 For information on how to use <code>gccgo</code>, a more traditional
 compiler using the GCC back end, see
-<a href="gccgo_install.html">Setting up and using gccgo</a>.
+<a href="/install/gccgo/">Setting up and using gccgo</a>.
 </p>
 
 <p>
@@ -226,7 +226,7 @@ If you see the "hello, world" message then Go is installed correctly.\n \n <p>\n Start by taking <a href="http://code.google.com/p/go-tour/">A Tour of Go</a>\n-or reading the <a href="go_tutorial.html">Go Tutorial</a>.\n+or reading the <a href="/doc/go_tutorial.html">Go Tutorial</a>.\n </p>\n \n <p>\n@@ -235,18 +235,18 @@ read <a href="/doc/code.html">How to Write Go Code</a>.\n </p>\n \n <p>\n-Build a web application by following the <a href="codelab/wiki/">Wiki\n+Build a web application by following the <a href="/doc/codelab/wiki/">Wiki\n Codelab</a>.\n </p>\n \n <p>\n-Read <a href="effective_go.html">Effective Go</a> to learn about writing\n+Read <a href="/doc/effective_go.html">Effective Go</a> to learn about writing\n idiomatic Go code.\n </p>\n \n <p>\n For the full story, consult Go\'s extensive \n-<a href="docs.html">documentation</a>.\n+<a href="/doc/">documentation</a>.\n </p>

doc/install-source.html の変更点:

gccgo_install.html → /install/gccgo/: gccgo のインストールに関するリンクが修正されました。これは、gccgo のドキュメントが /install/ パス以下に配置されていることを示唆しています。
go_tutorial.html → /doc/go_tutorial.html: Goチュートリアルへのリンクが修正されました。Goの主要なドキュメントは /doc/ パス以下に配置されています。
codelab/wiki/ → /doc/codelab/wiki/: Wiki Codelabへのリンクが修正されました。これも /doc/ パス以下に移動しています。
effective_go.html → /doc/effective_go.html: Effective Goへのリンクが修正されました。これも /doc/ パス以下に移動しています。
docs.html → /doc/: Goの広範なドキュメント全体へのリンクが修正されました。これは、ドキュメントのトップページが /doc/ であることを示しています。

--- a/doc/install.html
+++ b/doc/install.html
@@ -153,18 +153,18 @@ read <a href="/doc/code.html">How to Write Go Code</a>.\n </p>\n \n <p>\n-Build a web application by following the <a href="codelab/wiki/">Wiki\n+Build a web application by following the <a href="/doc/codelab/wiki/">Wiki\n Codelab</a>.\n </p>\n \n <p>\n-Read <a href="effective_go.html">Effective Go</a> to learn about writing\n+Read <a href="/doc/effective_go.html">Effective Go</a> to learn about writing\n idiomatic Go code.\n </p>\n \n <p>\n For the full story, consult Go\'s extensive \n-<a href="docs.html">documentation</a>.\n+<a href="/doc/">documentation</a>.\n </p>

doc/install.html の変更点:

doc/install-source.html と同様に、codelab/wiki/、effective_go.html、docs.html へのリンクがそれぞれ /doc/codelab/wiki/、/doc/effective_go.html、/doc/ に修正されています。

これらの変更はすべて、相対パスで記述されていた内部リンクを、Webサイトのルートからの絶対パスに変換することで、リンクの堅牢性を高め、リンク切れを防ぐことを目的としています。これにより、ユーザーはGoのインストール手順を参照する際に、常に正しいドキュメントにアクセスできるようになります。

参考にした情報源リンク

HTML <a> タグ: https://developer.mozilla.org/ja/docs/Web/HTML/Element/a
相対パスと絶対パス: https://developer.mozilla.org/ja/docs/Learn/Common_questions/What_is_a_URL#Absolute_and_relative_URLs
Gerrit Code Review: https://www.gerritcodereview.com/
Go言語公式ドキュメント: https://golang.org/doc/

comemo